Split runtime into types/params/helpers sub-packages

Restructure the runtime package generation from a single monolithic file
into three sub-packages for better organization and independent imports:

- runtime/types: custom Go types (Date, Email, UUID, File, Nullable)
- runtime/params: parameter serialization/deserialization functions
- runtime/helpers: utility functions (MarshalForm)

Key changes:
- Replace single RuntimePrefix with category-specific prefixes
  (RuntimeParamsPrefix, RuntimeTypesPrefix, RuntimeHelpersPrefix)
- Add {{ typesPrefix }} template function to param templates so
  params can reference types.Date/types.DateFormat across packages
- Update all generators and templates for split prefixes
- GenerateRuntime() now returns RuntimeOutput with three fields
- CLI --generate-runtime creates three sub-directories
- Restructure internal/codegen to codegen/internal with public API
- Update webhook example to use shared runtime package
- Document runtime-package, webhook, and callback config options

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: mromaszewicz

experimental/Configuration.md

@@ -30,13 +30,47 @@ generation:
   # Default: false
   simple-client: true
 
+  # Generate webhook initiator code (sends webhook requests to target URLs).
+  # Generates a framework-agnostic client that takes the full target URL per-call.
+  # Default: false
+  webhook-initiator: true
+
+  # Generate webhook receiver code (receives webhook requests).
+  # Generates framework-specific handler functions. Requires server to be set.
+  # Default: false
+  webhook-receiver: true
+
+  # Generate callback initiator code (sends callback requests to target URLs).
+  # Default: false
+  callback-initiator: true
+
+  # Generate callback receiver code (receives callback requests).
+  # Generates framework-specific handler functions. Requires server to be set.
+  # Default: false
+  callback-receiver: true
+
   # Use model types from an external package instead of generating them locally.
   # When set, models are imported rather than generated.
   # Default: not set (models are generated locally)
   models-package:
     path: github.com/org/project/models
     alias: models  # optional, defaults to last segment of path
 
+  # Use a shared runtime package instead of embedding helpers in each generated file.
+  # When set, custom types (Date, Email, UUID, File, Nullable), parameter
+  # serialization functions, and helper functions (MarshalForm) are NOT embedded
+  # in the output. Instead, the generated code imports them from three sub-packages:
+  #   <path>/types   — custom types (Date, Email, UUID, File, Nullable)
+  #   <path>/params  — parameter style/bind functions (StyleSimpleParam, BindFormParam, etc.)
+  #   <path>/helpers — utility functions (MarshalForm)
+  #
+  # Generate the runtime package once with:
+  #   oapi-codegen --generate-runtime <base-import-path>
+  #
+  # Default: not set (all helpers are embedded in each generated file)
+  runtime-package:
+    path: github.com/org/project/runtime
+
 # Output options: control which operations and schemas are included.
 output-options:
   # Only include operations tagged with one of these tags. Ignored when empty.

experimental/cmd/oapi-codegen/main.go

@@ -15,13 +15,14 @@ import (
 
 	"gopkg.in/yaml.v3"
 
-	"github.com/oapi-codegen/oapi-codegen-exp/experimental/internal/codegen"
+	"github.com/oapi-codegen/oapi-codegen-exp/experimental/codegen"
 )
 
 func main() {
 	configPath := flag.String("config", "", "path to configuration file")
 	flagPackage := flag.String("package", "", "Go package name for generated code")
 	flagOutput := flag.String("output", "", "output file path (default: <spec-basename>.gen.go)")
+	flagGenerateRuntime := flag.String("generate-runtime", "", "generate runtime sub-packages (types, params, helpers) under the output directory; value is the base import path (no spec required)")
 	flag.Usage = func() {
 		fmt.Fprintf(os.Stderr, "Usage: %s [options] <spec-path-or-url>\n\n", os.Args[0])
 		fmt.Fprintf(os.Stderr, "Arguments:\n")
@@ -31,6 +32,42 @@ func main() {
 	}
 	flag.Parse()
 
+	// --generate-runtime mode: produce three runtime sub-packages and exit.
+	if *flagGenerateRuntime != "" {
+		rt, err := codegen.GenerateRuntime(*flagGenerateRuntime)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "error generating runtime: %v\n", err)
+			os.Exit(1)
+		}
+		// Output directory defaults to current directory.
+		outputDir := *flagOutput
+		if outputDir == "" {
+			outputDir = "."
+		}
+		// Write each sub-package into its own subdirectory.
+		subPkgs := []struct {
+			dir, file, code string
+		}{
+			{"types", "types.gen.go", rt.Types},
+			{"params", "params.gen.go", rt.Params},
+			{"helpers", "helpers.gen.go", rt.Helpers},
+		}
+		for _, sp := range subPkgs {
+			dir := filepath.Join(outputDir, sp.dir)
+			if err := os.MkdirAll(dir, 0755); err != nil {
+				fmt.Fprintf(os.Stderr, "error creating directory %s: %v\n", dir, err)
+				os.Exit(1)
+			}
+			path := filepath.Join(dir, sp.file)
+			if err := os.WriteFile(path, []byte(sp.code), 0644); err != nil {
+				fmt.Fprintf(os.Stderr, "error writing %s: %v\n", path, err)
+				os.Exit(1)
+			}
+			fmt.Printf("Generated %s\n", path)
+		}
+		return
+	}
+
 	if flag.NArg() != 1 {
 		flag.Usage()
 		os.Exit(1)

experimental/codegen/codegen.go

@@ -0,0 +1,54 @@
+// Package codegen provides the public API for oapi-codegen's experimental code generator.
+//
+// This package re-exports the core types and functions from the internal
+// implementation, providing a stable public interface for external consumers.
+package codegen
+
+import (
+	"github.com/pb33f/libopenapi"
+
+	impl "github.com/oapi-codegen/oapi-codegen-exp/experimental/codegen/internal"
+)
+
+// Configuration is the top-level configuration for code generation.
+type Configuration = impl.Configuration
+
+// GenerationOptions controls which parts of the code are generated.
+type GenerationOptions = impl.GenerationOptions
+
+// OutputOptions controls filtering of operations and schemas.
+type OutputOptions = impl.OutputOptions
+
+// ModelsPackage specifies an external package containing the model types.
+type ModelsPackage = impl.ModelsPackage
+
+// TypeMapping allows customizing OpenAPI type/format to Go type mappings.
+type TypeMapping = impl.TypeMapping
+
+// NameMangling configures how OpenAPI names are converted to Go identifiers.
+type NameMangling = impl.NameMangling
+
+// NameSubstitutions allows direct overrides of generated names.
+type NameSubstitutions = impl.NameSubstitutions
+
+// StructTagsConfig configures how struct tags are generated for fields.
+type StructTagsConfig = impl.StructTagsConfig
+
+// RuntimePackageConfig specifies an external package containing runtime helpers.
+type RuntimePackageConfig = impl.RuntimePackageConfig
+
+// RuntimeOutput holds the generated code for each runtime sub-package.
+type RuntimeOutput = impl.RuntimeOutput
+
+// Generate produces Go code from the parsed OpenAPI document.
+// specData is the raw spec bytes used to embed the spec in the generated code.
+func Generate(doc libopenapi.Document, specData []byte, cfg Configuration) (string, error) {
+	return impl.Generate(doc, specData, cfg)
+}
+
+// GenerateRuntime produces standalone Go source files for each of the three
+// runtime sub-packages (types, params, helpers). baseImportPath is the base
+// import path for the runtime module (e.g., "github.com/org/project/runtime").
+func GenerateRuntime(baseImportPath string) (*RuntimeOutput, error) {
+	return impl.GenerateRuntime(baseImportPath)
+}

…perimental/internal/codegen/clientgen.go …perimental/codegen/internal/clientgen.goexperimental/internal/codegen/clientgen.go renamed to experimental/codegen/internal/clientgen.go experimental/internal/codegen/clientgen.go renamed to experimental/codegen/internal/clientgen.go

@@ -6,7 +6,7 @@ import (
 	"strings"
 	"text/template"
 
-	"github.com/oapi-codegen/oapi-codegen-exp/experimental/internal/codegen/templates"
+	"github.com/oapi-codegen/oapi-codegen-exp/experimental/codegen/internal/templates"
 )
 
 // ClientGenerator generates client code from operation descriptors.
@@ -19,8 +19,13 @@ type ClientGenerator struct {
 
 // NewClientGenerator creates a new client generator.
 // modelsPackage can be nil if models are in the same package.
-func NewClientGenerator(schemaIndex map[string]*SchemaDescriptor, generateSimple bool, modelsPackage *ModelsPackage) (*ClientGenerator, error) {
-	tmpl := template.New("client").Funcs(templates.Funcs()).Funcs(clientFuncs(schemaIndex, modelsPackage))
+// rp holds the package prefixes for runtime sub-packages; all empty when embedded.
+func NewClientGenerator(schemaIndex map[string]*SchemaDescriptor, generateSimple bool, modelsPackage *ModelsPackage, rp RuntimePrefixes) (*ClientGenerator, error) {
+	tmpl := template.New("client").Funcs(templates.Funcs()).Funcs(clientFuncs(schemaIndex, modelsPackage)).Funcs(template.FuncMap{
+		"runtimeParamsPrefix":  func() string { return rp.Params },
+		"runtimeTypesPrefix":   func() string { return rp.Types },
+		"runtimeHelpersPrefix": func() string { return rp.Helpers },
+	})
 
 	// Parse client templates
 	for _, ct := range templates.ClientTemplates {

…ental/internal/codegen/clientgen_test.go …ental/codegen/internal/clientgen_test.goexperimental/internal/codegen/clientgen_test.go renamed to experimental/codegen/internal/clientgen_test.go experimental/internal/codegen/clientgen_test.go renamed to experimental/codegen/internal/clientgen_test.go

@@ -51,7 +51,7 @@ func TestClientGenerator(t *testing.T) {
 	t.Logf("Operations: %v", operationIDs)
 
 	// Generate client code
-	gen, err := NewClientGenerator(schemaIndex, true, nil)
+	gen, err := NewClientGenerator(schemaIndex, true, nil, RuntimePrefixes{})
 	require.NoError(t, err, "Failed to create client generator")
 
 	clientCode, err := gen.GenerateClient(ops)
@@ -119,23 +119,23 @@ func TestClientGenerator_FormEncoded(t *testing.T) {
 	require.True(t, hasFormBody, "Expected at least one operation with a form-encoded typed body")
 
 	// Generate client code
-	gen, err := NewClientGenerator(schemaIndex, true, nil)
+	gen, err := NewClientGenerator(schemaIndex, true, nil, RuntimePrefixes{})
 	require.NoError(t, err, "Failed to create client generator")
 
 	clientCode, err := gen.GenerateClient(ops)
 	require.NoError(t, err, "Failed to generate client code")
 
 	t.Logf("Generated client code:\n%s", clientCode)
 
-	// Verify form-encoded body methods reference marshalForm
-	require.Contains(t, clientCode, "marshalForm(body)")
+	// Verify form-encoded body methods reference MarshalForm
+	require.Contains(t, clientCode, "MarshalForm(body)")
 
 	// Verify we generate the form helper when needed
 	ctx.NeedFormHelper(ops)
 	formHelper, err := generateMarshalFormHelper()
 	require.NoError(t, err, "Failed to generate form helper")
 	require.NotEmpty(t, formHelper, "Form helper should be generated when form-encoded bodies exist")
-	require.Contains(t, formHelper, "func marshalForm(")
+	require.Contains(t, formHelper, "func MarshalForm(")
 	require.Contains(t, formHelper, "func marshalFormImpl(")
 	require.Contains(t, formHelper, "reflect.Value")
 

experimental/internal/codegen/codegen.go experimental/codegen/internal/codegen.goexperimental/internal/codegen/codegen.go renamed to experimental/codegen/internal/codegen.go

@@ -9,7 +9,7 @@ import (
 	"github.com/pb33f/libopenapi"
 	"github.com/pb33f/libopenapi/datamodel/high/base"
 
-	"github.com/oapi-codegen/oapi-codegen-exp/experimental/internal/codegen/templates"
+	"github.com/oapi-codegen/oapi-codegen-exp/experimental/codegen/internal/templates"
 )
 
 // Generate produces Go code from the parsed OpenAPI document.
@@ -20,6 +20,17 @@ func Generate(doc libopenapi.Document, specData []byte, cfg Configuration) (stri
 	// Create a single CodegenContext that all generators share.
 	ctx := NewCodegenContext()
 
+	// Configure runtime package prefixes if an external runtime is specified.
+	var runtimePrefixes RuntimePrefixes
+	if cfg.Generation.RuntimePackage != nil {
+		runtimePrefixes = RuntimePrefixes{
+			Params:  "params.",
+			Types:   "types.",
+			Helpers: "helpers.",
+		}
+		ctx.SetRuntimePrefixes(runtimePrefixes.Params, runtimePrefixes.Types, runtimePrefixes.Helpers)
+	}
+
 	// Create content type matcher for filtering request/response bodies
 	contentTypeMatcher := NewContentTypeMatcher(cfg.ContentTypes)
 
@@ -102,7 +113,7 @@ func Generate(doc libopenapi.Document, specData []byte, cfg Configuration) (stri
 
 		ops = FilterOperations(ops, cfg.OutputOptions)
 
-		clientGen, err := NewClientGenerator(schemaIndex, cfg.Generation.SimpleClient, cfg.Generation.ModelsPackage)
+		clientGen, err := NewClientGenerator(schemaIndex, cfg.Generation.SimpleClient, cfg.Generation.ModelsPackage, runtimePrefixes)
 		if err != nil {
 			return "", fmt.Errorf("creating client generator: %w", err)
 		}
@@ -140,7 +151,7 @@ func Generate(doc libopenapi.Document, specData []byte, cfg Configuration) (stri
 		ops = FilterOperations(ops, cfg.OutputOptions)
 
 		if len(ops) > 0 {
-			serverGen, err := NewServerGenerator(cfg.Generation.Server)
+			serverGen, err := NewServerGenerator(cfg.Generation.Server, runtimePrefixes)
 			if err != nil {
 				return "", fmt.Errorf("creating server generator: %w", err)
 			}
@@ -171,7 +182,7 @@ func Generate(doc libopenapi.Document, specData []byte, cfg Configuration) (stri
 		}
 
 		if len(webhookOps) > 0 {
-			initiatorGen, err := NewInitiatorGenerator("Webhook", schemaIndex, true, cfg.Generation.ModelsPackage)
+			initiatorGen, err := NewInitiatorGenerator("Webhook", schemaIndex, true, cfg.Generation.ModelsPackage, runtimePrefixes)
 			if err != nil {
 				return "", fmt.Errorf("creating webhook initiator generator: %w", err)
 			}
@@ -202,7 +213,7 @@ func Generate(doc libopenapi.Document, specData []byte, cfg Configuration) (stri
 		}
 
 		if len(callbackOps) > 0 {
-			initiatorGen, err := NewInitiatorGenerator("Callback", schemaIndex, true, cfg.Generation.ModelsPackage)
+			initiatorGen, err := NewInitiatorGenerator("Callback", schemaIndex, true, cfg.Generation.ModelsPackage, runtimePrefixes)
 			if err != nil {
 				return "", fmt.Errorf("creating callback initiator generator: %w", err)
 			}
@@ -237,7 +248,7 @@ func Generate(doc libopenapi.Document, specData []byte, cfg Configuration) (stri
 		}
 
 		if len(webhookOps) > 0 {
-			receiverGen, err := NewReceiverGenerator("Webhook", cfg.Generation.Server)
+			receiverGen, err := NewReceiverGenerator("Webhook", cfg.Generation.Server, runtimePrefixes)
 			if err != nil {
 				return "", fmt.Errorf("creating webhook receiver generator: %w", err)
 			}
@@ -288,7 +299,7 @@ func Generate(doc libopenapi.Document, specData []byte, cfg Configuration) (stri
 		}
 
 		if len(callbackOps) > 0 {
-			receiverGen, err := NewReceiverGenerator("Callback", cfg.Generation.Server)
+			receiverGen, err := NewReceiverGenerator("Callback", cfg.Generation.Server, runtimePrefixes)
 			if err != nil {
 				return "", fmt.Errorf("creating callback receiver generator: %w", err)
 			}
@@ -329,31 +340,47 @@ func Generate(doc libopenapi.Document, specData []byte, cfg Configuration) (stri
 
 	// ── Phase 2: Render helpers ──
 
-	// Emit custom type templates (Date, Email, UUID, File, Nullable, etc.)
-	for _, templateName := range ctx.RequiredCustomTypes() {
-		typeCode := ctx.loadAndRegisterCustomType(templateName)
-		if typeCode != "" {
-			output.AddType(typeCode)
+	if cfg.Generation.RuntimePackage != nil {
+		// Runtime package is configured — don't embed helpers, import them.
+		// Add imports for whichever sub-packages are actually needed.
+		ctx.AddImport(cfg.Generation.RuntimePackage.TypesImport())
+		if ctx.HasAnyParams() {
+			ctx.AddImport(cfg.Generation.RuntimePackage.ParamsImport())
+		}
+		if len(ctx.RequiredHelpers()) > 0 {
+			ctx.AddImport(cfg.Generation.RuntimePackage.HelpersImport())
+		}
+	} else {
+		// Resolve param template dependencies first — this may register
+		// additional custom types (e.g., Date) that need to be emitted.
+		ctx.GetRequiredParamTemplates()
+
+		// Emit custom type templates (Date, Email, UUID, File, Nullable, etc.)
+		for _, templateName := range ctx.RequiredCustomTypes() {
+			typeCode := ctx.loadAndRegisterCustomType(templateName)
+			if typeCode != "" {
+				output.AddType(typeCode)
+			}
 		}
-	}
-
-	// Emit param functions
-	paramFuncs, err := generateParamFunctionsFromContext(ctx)
-	if err != nil {
-		return "", fmt.Errorf("generating param functions: %w", err)
-	}
-	if paramFuncs != "" {
-		output.AddType(paramFuncs)
-	}
 
-	// Emit helper templates (e.g., marshal_form)
-	for _, helperName := range ctx.RequiredHelpers() {
-		helperCode, err := generateHelper(helperName, ctx)
+		// Emit param functions (typesPrefix is empty when embedded — Date is in same package)
+		paramFuncs, err := generateParamFunctionsFromContext(ctx, "")
 		if err != nil {
-			return "", fmt.Errorf("generating helper %s: %w", helperName, err)
+			return "", fmt.Errorf("generating param functions: %w", err)
+		}
+		if paramFuncs != "" {
+			output.AddType(paramFuncs)
 		}
-		if helperCode != "" {
-			output.AddType(helperCode)
+
+		// Emit helper templates (e.g., marshal_form)
+		for _, helperName := range ctx.RequiredHelpers() {
+			helperCode, err := generateHelper(helperName, ctx)
+			if err != nil {
+				return "", fmt.Errorf("generating helper %s: %w", helperName, err)
+			}
+			if helperCode != "" {
+				output.AddType(helperCode)
+			}
 		}
 	}
 
@@ -397,7 +424,8 @@ func generateMarshalFormHelper() (string, error) {
 }
 
 // generateParamFunctionsFromContext generates the parameter styling/binding functions based on CodegenContext usage.
-func generateParamFunctionsFromContext(ctx *CodegenContext) (string, error) {
+// typesPrefix is prepended to Date/DateFormat references in param templates; empty when embedded.
+func generateParamFunctionsFromContext(ctx *CodegenContext, typesPrefix string) (string, error) {
 	if !ctx.HasAnyParams() {
 		return "", nil
 	}
@@ -412,7 +440,9 @@ func generateParamFunctionsFromContext(ctx *CodegenContext) (string, error) {
 			return "", fmt.Errorf("reading param template %s: %w", tmplInfo.Template, err)
 		}
 
-		tmpl, err := template.New(tmplInfo.Name).Parse(string(content))
+		tmpl, err := template.New(tmplInfo.Name).Funcs(template.FuncMap{
+			"typesPrefix": func() string { return typesPrefix },
+		}).Parse(string(content))
 		if err != nil {
 			return "", fmt.Errorf("parsing param template %s: %w", tmplInfo.Template, err)
 		}