Go Core & IR

Module: github.com/redelay/go-framework/core

Overview

The core/ packages in go-framework handle the framework-specific compilation concerns: AsyncAPI and OpenAPI format integration, the full compile pipeline that adds those formats, and the migration executor.

The canonical IR types, base compile pipeline, FlowDSL parser, structural validation, dependency resolver, diagnostics, metadata, schema generation, and all module file/gen/svg tooling have moved to the standalone go-flowdsl library at github.com/redelay/go-flowdsl. See the go-flowdsl Reference for those packages.

Package overview

Packages in go-framework/core (this document)

Packages that moved to go-flowdsl

Full compile pipeline (core/compile)

core/compile wraps go-flowdsl/compile and registers the asyncapi and openapi importers and exporters so the full suite of formats is available in one package.

Importing core/compile (or any package that imports it) is sufficient to register all four formats. Applications that only need flowdsl and businessmodel can use go-flowdsl/compile directly with no dependency on go-framework.

import "github.com/redelay/go-framework/core/compile"

// Step 1: Import a source format into IR.
// Supported formats: flowdsl, businessmodel, openapi, asyncapi.
doc, err := compile.Import(compile.FormatFlowDSL, reader)

// Step 2: Validate + resolve + enrich.
result := compile.Compile(doc)
result.Document    // enriched *ir.Document
result.Diagnostics // *diagnostics.Collector
result.Modules     // []*ir.Module in dependency order
result.HasErrors() // bool

// One-step import + compile.
result, err := compile.ImportAndCompile(compile.FormatOpenAPI, reader)

// Export IR to a format.
err = compile.Export(doc, compile.FormatFlowDSL, writer)

Supported formats

The FormatFlowDSL and FormatBusinessModel constants and their handlers come from go-flowdsl/compile. FormatOpenAPI and FormatAsyncAPI are registered by go-framework/core/openapi and go-framework/core/asyncapi respectively.

Compilation stages

1. Validate — structural correctness (IDs, references, module naming conventions)
2. Resolve — topological sort of modules by dependencies (Kahn's algorithm)
3. Enrich — promote module-level entities/events/actions/workflows to document level; warn on unresolved provides

AsyncAPI (core/asyncapi)

Imports and exports AsyncAPI 2.6 YAML documents as ir.Document values.

import "github.com/redelay/go-framework/core/asyncapi"

// Import an AsyncAPI document.
doc, err := asyncapi.Import(reader) // io.Reader → *ir.Document

// Export IR to AsyncAPI YAML.
err = asyncapi.Export(doc, writer)

This package is typically consumed through core/compile rather than called directly. It registers itself as an importer for the "asyncapi" format on package init.

OpenAPI (core/openapi)

The core/openapi package provides three distinct capabilities:

1. Import — parse an existing OpenAPI 3.0 spec into ir.Document
2. Export — serialize ir.Document to an OpenAPI tool-schema JSON for LLM/MCP use
3. Spec generation — generate an OpenAPI 3.0 spec at runtime from registered HTTP routes

Import and export

import "github.com/redelay/go-flowdsl/openapi"

// Import an OpenAPI YAML/JSON spec.
doc, err := openapi.Import(reader)

// Export IR as OpenAPI tool schema.
err = openapi.Export(doc, writer)

Like asyncapi, this is typically consumed through core/compile.

Spec generation

The runtime OpenAPI spec generator builds a full openapi.json from routes declared via modules.EndpointMeta functional options. This is what powers the /openapi.json endpoint and the interactive API docs UI.

Routes declare metadata via functional options on the router:

r.Handle("POST", "/", handler,
    modules.Summary("Create user"),
    modules.Body(UserCreateInput{}),
    modules.Response(201, "User created", UserResponse{}),
    modules.Response(400, "Bad request", modules.RedelayErrorResponse{}),
    modules.Security("BearerAuth"),
)

SchemaRegistry — converts Go structs to JSON Schema via reflection. Handles json tags, validate tags (required, email, min, max), pointer nullability, time.Time, ObjectID, slices, maps, and embedded structs.

Security schemes are configured via SpecOption:

Schema naming convention — all API schemas use module-prefixed names:

Migration executor (core/migrate)

Runs database migration definitions sourced from an ir.Document.

import "github.com/redelay/go-framework/core/migrate"

executor := migrate.New(migrate.Options{
    DB:     db,     // *sql.DB or compatible
    Logger: logger,
})
err := executor.Run(ctx, doc)

Each ir.Migration in the document describes a backend, version, and up/down SQL. The executor applies migrations in version order, tracking applied versions to avoid re-running.

For IR types, the base compile pipeline, FlowDSL parser, validate, resolver, diagnostics, metadata, schema, and module file/gen/svg tools — see the go-flowdsl Reference.