feat: add HTTP migration bridges and extensible API binding

2026-09-24 01:47:42 +08:00
parent 7b8eca1a61
commit a8c973d8a2
39 changed files with 2596 additions and 118 deletions
--- a/cmd/go-omni/apigen/generate.go
+++ b/cmd/go-omni/apigen/generate.go
@@ -19,7 +19,7 @@ import (
 )

 const frameworkModule = "git.yuntuo.hk/k2safe/go-omni"
-const minimumVersion = "v0.8.0-preview"
+const minimumVersion = "v0.9.0-preview"
 const generatedHeader = "// Code generated by go-omni api. DO NOT EDIT.\n"

 type Options struct {
@@ -94,6 +94,16 @@ func generate(o Options, c *Compiled, starter bool) (Output, error) {
 		return Output{}, err
 	}
 	o.Dir = directory
+	for _, r := range c.Spec.Routes {
+		if !r.Manual {
+			path := filepath.Join(directory, "internal/handler", r.Group, lower(r.Handler)+"Manual.go")
+			if _, err := os.Lstat(path); err == nil {
+				return Output{}, fmt.Errorf("manual handler %s exists; migrate and remove it explicitly before switching to automatic generation", path)
+			} else if !errors.Is(err, os.ErrNotExist) {
+				return Output{}, err
+			}
+		}
+	}
 	if err := resolveProfile(&o); err != nil {
 		return Output{}, err
 	}
@@ -130,13 +140,13 @@ func generate(o Options, c *Compiled, starter bool) (Output, error) {
 					if !filepath.IsAbs(path) {
 						path = filepath.Join(directory, path)
 					}
-					if _, err := os.Stat(filepath.Join(path, "httpx", "response.go")); err == nil {
+					if _, err := os.Stat(filepath.Join(path, "contract", "scalar.go")); err == nil {
 						localCurrent = true
 					}
 				}
 			}
 			if !localCurrent {
-				return Output{}, fmt.Errorf("existing framework dependency predates configurable responses; use %s or a current local replacement", minimumVersion)
+				return Output{}, fmt.Errorf("existing framework dependency predates migration extensions; use %s or a current local replacement", minimumVersion)
 			}
 		}
 		if o.FrameworkDir != "" {
@@ -309,6 +319,20 @@ func renderProject(o Options, c *Compiled, starter bool) (map[string][]byte, map
 		put(generated, "internal/apierrors/errorsGen.go", generatedHeader+content)
 	}
 	types := "package types\n\n"
+	if len(c.Spec.Scalars) > 0 {
+		types += "import("
+		for i, d := range c.Spec.Scalars {
+			types += fmt.Sprintf("scalar%d %q;", i, d.GoImport)
+		}
+		types += ")\n"
+		registry := fmt.Sprintf("package types\nimport %q\nfunc ContractScalars()[]contract.Scalar{return []contract.Scalar{", frameworkModule+"/contract")
+		for i, d := range c.Spec.Scalars {
+			types += fmt.Sprintf("type %s = scalar%d.%s\n", d.Name, i, d.GoType)
+			registry += fmt.Sprintf("contract.ScalarOf[%s](%q,%q,%t),", d.Name, d.JSONInput, d.JSONOutput, d.Text)
+		}
+		registry += "}}\n"
+		put(generated, "internal/types/scalarsGen.go", generatedHeader+registry)
+	}
 	for _, t := range c.Spec.Types {
 		types += "type " + t.Name + " struct {\n"
 		for _, f := range t.Fields {
@@ -331,6 +355,10 @@ func renderProject(o Options, c *Compiled, starter bool) (map[string][]byte, map
 	put(generated, "internal/handler/responseGen.go", generatedHeader+policySource)
 	imports := fmt.Sprintf("import (\"fmt\"; %q; %q; %q;", frameworkModule+"/httpx", frameworkModule+"/openapi", o.Module+"/internal/servicecontext")
 	routes := "func RegisterRoutes(router openapi.Registrar, deps *servicecontext.Context) error {\n if router==nil || deps==nil {return fmt.Errorf(\"router and dependencies required\")}\n"
+	if len(c.Spec.Scalars) > 0 {
+		imports += fmt.Sprintf("%q;%q;", frameworkModule+"/contract", o.Module+"/internal/types")
+		routes += "if err:=contract.ValidateScalars(types.ContractScalars()...);err!=nil{return err}\n"
+	}
 	middlewareSet := map[string]bool{}
 	for _, r := range c.Spec.Routes {
 		for _, m := range r.Middleware {
@@ -347,7 +375,7 @@ func renderProject(o Options, c *Compiled, starter bool) (map[string][]byte, map
 	}
 	for i, group := range c.Groups {
 		imports += fmt.Sprintf("h%d %q; s%d %q;", i, o.Module+"/internal/handler/"+group, i, o.Module+"/internal/service/"+group)
-		routes += fmt.Sprintf("h%d := h%d.New(s%d.New(deps))\n", i, i, i)
+		routes += fmt.Sprintf("h%d := h%d.New(s%d.New(deps),deps)\n", i, i, i)
 		groupRoutes := []Route{}
 		for _, r := range c.Spec.Routes {
 			if r.Group == group {
@@ -356,12 +384,16 @@ func renderProject(o Options, c *Compiled, starter bool) (map[string][]byte, map
 		}
 		packageName := filepath.Base(group)
 		text := "package " + packageName + "\nimport(\"context\"; \"fmt\";"
-		needsTypes, needsBinder := false, false
+		needsTypes, needsBinder, hasAutomatic := false, false, false
 		for _, r := range groupRoutes {
+			if r.Manual {
+				continue
+			}
+			hasAutomatic = true
 			needsTypes = needsTypes || r.Request != "" || r.Response != ""
-			needsBinder = needsBinder || r.Request != ""
+			needsBinder = needsBinder || (r.Request != "" && !r.CustomBinding)
 		}
-		text += fmt.Sprintf("%q;", frameworkModule+"/httpx")
+		text += fmt.Sprintf("%q;%q;", frameworkModule+"/httpx", o.Module+"/internal/servicecontext")
 		if needsTypes {
 			text += fmt.Sprintf("%q;", o.Module+"/internal/types")
 		}
@@ -371,18 +403,47 @@ func renderProject(o Options, c *Compiled, starter bool) (map[string][]byte, map
 		text += ")\n"
 		text += "type Service interface {\n"
 		for _, r := range groupRoutes {
-			text += signature(r) + "\n"
+			if !r.Manual {
+				text += signature(r) + "\n"
+			}
 		}
-		text += "}\ntype Handler struct {service Service}\nfunc New(s Service)*Handler {return &Handler{service:s}}\n"
+		text += "}\ntype Handler struct {service Service;deps *servicecontext.Context}\nfunc New(s Service,deps ...*servicecontext.Context)*Handler {h:=&Handler{service:s};if len(deps)>0{h.deps=deps[0]};return h}\n"
 		for _, r := range groupRoutes {
 			name := upper(r.Handler)
-			if r.Request != "" {
-				text += fmt.Sprintf("var %sRequest = contract.MustNew[types.%s]()\n", lower(r.Handler), r.Request)
+			// The response policy and body reader cap are installed before App middleware.
+			if r.MaxBodyBytes > 0 {
+				routes += fmt.Sprintf("httpx.HandleWithBodyLimit(router,%q,%q,%d,responseEncoder(%q,%t),h%d.%s", strings.ToUpper(r.Method), r.Path, r.MaxBodyBytes, responseName(r), r.ResponseFormat == "raw", i, name)
+			} else {
+				routes += fmt.Sprintf("httpx.HandleWithResponse(router,%q,%q,responseEncoder(%q,%t),h%d.%s", strings.ToUpper(r.Method), r.Path, responseName(r), r.ResponseFormat == "raw", i, name)
+			}
+			for _, m := range r.Middleware {
+				routes += fmt.Sprintf(",deps.Middlewares[%q]", m)
+			}
+			routes += ")\n"
+			if r.Manual {
+				put(seeds, "internal/handler/"+group+"/"+lower(r.Handler)+"Manual.go", fmt.Sprintf("package %s\nimport(%q;apierrors %q)\n// %s owns raw/multipart binding and response output. h.deps holds project dependencies.\n// This file is preserved on regeneration.\nfunc(h *Handler)%s(c *httpx.Context)error{return apierrors.New(501,\"NOT_IMPLEMENTED\",\"manual handler is not implemented\")}\n", packageName, frameworkModule+"/httpx", frameworkModule+"/errors", name, name))
+				continue
+			}
+			if r.Request != "" && !r.CustomBinding {
+				scalarArgs := ""
+				if len(c.Spec.Scalars) > 0 {
+					scalarArgs = "types.ContractScalars()..."
+				}
+				text += fmt.Sprintf("var %sRequest = contract.MustNew[types.%s](%s)\n", lower(r.Handler), r.Request, scalarArgs)
 			}
 			text += fmt.Sprintf("func(h *Handler) %s(c *httpx.Context)error {\n", name)
 			call := "c.Context()"
 			if r.Request != "" {
-				text += fmt.Sprintf("var req types.%s\nif err:=%sRequest.Bind(c.Request(),httpx.RouteParams(c.Context()),&req);err!=nil{return err}\n", r.Request, lower(r.Handler))
+				if r.CustomBinding {
+					text += fmt.Sprintf("var req types.%s\nif err:=h.bind%s(c,&req);err!=nil{return err}\n", r.Request, name)
+					put(seeds, "internal/handler/"+group+"/"+lower(r.Handler)+"Bind.go", fmt.Sprintf("package %s\nimport(%q;%q;apierrors %q)\n// bind%s is project-owned; repeated generation preserves it.\nfunc(h *Handler)bind%s(c *httpx.Context,req *types.%s)error{return apierrors.New(501,\"BINDING_NOT_IMPLEMENTED\",\"custom binding is not implemented\")}\n", packageName, frameworkModule+"/httpx", o.Module+"/internal/types", frameworkModule+"/errors", name, name, r.Request))
+				} else {
+					limit := ""
+					if r.MaxBodyBytes > 0 {
+						limit = fmt.Sprintf(",%d", r.MaxBodyBytes)
+					}
+					text += fmt.Sprintf("var req types.%s\nif err:=%sRequest.Bind(c.Request(),httpx.RouteParams(c.Context()),&req%s);err!=nil{return err}\n", r.Request, lower(r.Handler), limit)
+				}
 				call += ", &req"
 			}
 			if r.Response != "" {
@@ -392,11 +453,6 @@ func renderProject(o Options, c *Compiled, starter bool) (map[string][]byte, map
 			} else {
 				text += fmt.Sprintf("if err:=h.service.%s(%s);err!=nil{return err};return c.NoContent()\n}\n", name, call)
 			}
-			routes += fmt.Sprintf("httpx.HandleWithResponse(router,%q,%q,responseEncoder(%q,%t),h%d.%s", strings.ToUpper(r.Method), r.Path, responseName(r), r.ResponseFormat == "raw", i, name)
-			for _, m := range r.Middleware {
-				routes += fmt.Sprintf(",deps.Middlewares[%q]", m)
-			}
-			routes += ")\n"
 			service := fmt.Sprintf("package %s\nimport(\"context\"; apierrors %q;", packageName, frameworkModule+"/errors")
 			if r.Request != "" || r.Response != "" {
 				service += fmt.Sprintf("%q;", o.Module+"/internal/types")
@@ -417,6 +473,10 @@ func renderProject(o Options, c *Compiled, starter bool) (map[string][]byte, map
 			}
 			put(seeds, "internal/service/"+group+"/"+lower(r.Handler)+".go", service)
 		}
+		if !hasAutomatic {
+			text = strings.Replace(text, strconv.Quote(frameworkModule+"/httpx")+";", "", 1)
+			text = strings.Replace(text, "\"context\";", "", 1)
+		}
 		if !hasResponse(groupRoutes) {
 			text = strings.Replace(text, "\"fmt\";", "", 1)
 		}
@@ -464,7 +524,7 @@ func renderProject(o Options, c *Compiled, starter bool) (map[string][]byte, map
 }
 func hasResponse(routes []Route) bool {
 	for _, r := range routes {
-		if r.Response != "" {
+		if r.Response != "" && !r.Manual {
 			return true
 		}
 	}