353 lines
11 KiB
Go
353 lines
11 KiB
Go
package apigen
|
|
|
|
import (
|
|
"bytes"
|
|
"encoding/json"
|
|
"errors"
|
|
"fmt"
|
|
"go/ast"
|
|
goparser "go/parser"
|
|
gotoken "go/token"
|
|
"reflect"
|
|
"regexp"
|
|
"sort"
|
|
"strings"
|
|
|
|
"git.yuntuo.hk/k2safe/go-omni/contract"
|
|
"git.yuntuo.hk/k2safe/go-omni/httpx"
|
|
"git.yuntuo.hk/k2safe/go-omni/openapi"
|
|
)
|
|
|
|
type Compiled struct {
|
|
Spec *Spec
|
|
Bindings map[string]*contract.Binder
|
|
Document []byte
|
|
Groups []string
|
|
}
|
|
|
|
var exportedName = regexp.MustCompile(`^[A-Z][A-Za-z0-9]*$`)
|
|
var goName = regexp.MustCompile(`^[a-zA-Z][A-Za-z0-9]*$`)
|
|
var lowerName = regexp.MustCompile(`^[a-z][A-Za-z0-9]*$`)
|
|
var serviceName = regexp.MustCompile(`^[a-zA-Z][a-zA-Z0-9-]*$`)
|
|
var staticSegment = regexp.MustCompile(`^[A-Za-z0-9._~-]+$`)
|
|
|
|
func Compile(spec *Spec) (*Compiled, error) {
|
|
if spec == nil || len(spec.Routes) == 0 || !serviceName.MatchString(spec.Service) {
|
|
return nil, errors.New("api: valid service and routes required")
|
|
}
|
|
var prepareErr error
|
|
spec, prepareErr = prepareMetadata(spec)
|
|
if prepareErr != nil {
|
|
return nil, prepareErr
|
|
}
|
|
definitions := map[string]Type{}
|
|
for _, t := range spec.Types {
|
|
if t.Name == "ContractScalars" && len(spec.Scalars) > 0 {
|
|
return nil, errors.New("ContractScalars is reserved when declaring scalars")
|
|
}
|
|
if !exportedName.MatchString(t.Name) {
|
|
return nil, fmt.Errorf("%s: type names must be UpperCamelCase", t.Position)
|
|
}
|
|
if _, ok := definitions[t.Name]; ok {
|
|
return nil, fmt.Errorf("%s: duplicate type %s", t.Position, t.Name)
|
|
}
|
|
definitions[t.Name] = t
|
|
}
|
|
scalarTypes, scalarDefs, err := compileScalars(spec, definitions)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
resolved := map[string]reflect.Type{}
|
|
resolving := map[string]bool{}
|
|
var resolve func(string, int) (reflect.Type, error)
|
|
var expression func(ast.Expr, int) (reflect.Type, error)
|
|
primitives := map[string]reflect.Type{"any": reflect.TypeOf((*any)(nil)).Elem(), "string": reflect.TypeOf(""), "bool": reflect.TypeOf(false), "int": reflect.TypeOf(int(0)), "int8": reflect.TypeOf(int8(0)), "int16": reflect.TypeOf(int16(0)), "int32": reflect.TypeOf(int32(0)), "int64": reflect.TypeOf(int64(0)), "uint": reflect.TypeOf(uint(0)), "uint8": reflect.TypeOf(uint8(0)), "uint16": reflect.TypeOf(uint16(0)), "uint32": reflect.TypeOf(uint32(0)), "uint64": reflect.TypeOf(uint64(0)), "float32": reflect.TypeOf(float32(0)), "float64": reflect.TypeOf(float64(0))}
|
|
expression = func(e ast.Expr, depth int) (reflect.Type, error) {
|
|
if depth > 32 {
|
|
return nil, errors.New("type nesting exceeds 32")
|
|
}
|
|
switch e := e.(type) {
|
|
case *ast.Ident:
|
|
if t, ok := scalarTypes[e.Name]; ok {
|
|
return t, nil
|
|
}
|
|
if t, ok := primitives[e.Name]; ok {
|
|
return t, nil
|
|
}
|
|
return resolve(e.Name, depth+1)
|
|
case *ast.StarExpr:
|
|
if _, double := e.X.(*ast.StarExpr); double {
|
|
return nil, errors.New("multiple pointer levels unsupported")
|
|
}
|
|
t, err := expression(e.X, depth+1)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
return reflect.PointerTo(t), nil
|
|
case *ast.ArrayType:
|
|
if e.Len != nil {
|
|
return nil, errors.New("use slices, not fixed arrays")
|
|
}
|
|
t, err := expression(e.Elt, depth+1)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
return reflect.SliceOf(t), nil
|
|
case *ast.MapType:
|
|
key, ok := e.Key.(*ast.Ident)
|
|
if !ok || key.Name != "string" {
|
|
return nil, errors.New("map keys must be string")
|
|
}
|
|
t, err := expression(e.Value, depth+1)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
return reflect.MapOf(reflect.TypeOf(""), t), nil
|
|
default:
|
|
return nil, errors.New("unsupported type expression")
|
|
}
|
|
}
|
|
resolve = func(name string, depth int) (reflect.Type, error) {
|
|
if depth > 32 {
|
|
return nil, errors.New("type nesting exceeds 32")
|
|
}
|
|
if t, ok := resolved[name]; ok {
|
|
return t, nil
|
|
}
|
|
if resolving[name] {
|
|
return nil, fmt.Errorf("recursive type %s is unsupported", name)
|
|
}
|
|
typ, ok := definitions[name]
|
|
if !ok {
|
|
return nil, fmt.Errorf("unknown type %s", name)
|
|
}
|
|
resolving[name] = true
|
|
defer delete(resolving, name)
|
|
var fields []reflect.StructField
|
|
seen := map[string]bool{}
|
|
for _, f := range typ.Fields {
|
|
if !exportedName.MatchString(f.Name) || seen[f.Name] {
|
|
return nil, fmt.Errorf("%s: invalid or duplicate field %s", name, f.Name)
|
|
}
|
|
seen[f.Name] = true
|
|
expr, err := goparser.ParseExpr(f.Type)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
t, err := expression(expr, depth+1)
|
|
if err != nil {
|
|
return nil, fmt.Errorf("%s.%s: %w", name, f.Name, err)
|
|
}
|
|
fields = append(fields, reflect.StructField{Name: f.Name, Type: t, Tag: reflect.StructTag(f.Tag)})
|
|
}
|
|
t := reflect.StructOf(fields)
|
|
resolved[name] = t
|
|
return t, nil
|
|
}
|
|
c := &Compiled{Spec: spec, Bindings: map[string]*contract.Binder{}}
|
|
for _, t := range spec.Types {
|
|
rt, err := resolve(t.Name, 0)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
b, err := contract.Describe(rt, scalarDefs...)
|
|
if err != nil {
|
|
return nil, fmt.Errorf("%s: %w", t.Position, err)
|
|
}
|
|
c.Bindings[t.Name] = b
|
|
}
|
|
api, err := openapi.New(spec.Title, spec.Version)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
handlers, paths, shapes, groups := map[string]bool{}, map[string]bool{}, map[string]string{}, map[string]bool{}
|
|
middlewareSymbols := map[string]string{}
|
|
for _, r := range spec.Routes {
|
|
if !goName.MatchString(r.Handler) {
|
|
return nil, fmt.Errorf("%s: invalid handler name", r.Position)
|
|
}
|
|
if strings.EqualFold(r.Handler, "service") {
|
|
return nil, errors.New("handler name service conflicts with the service constructor file")
|
|
}
|
|
if r.Group == "" {
|
|
return nil, errors.New("group required")
|
|
}
|
|
for _, part := range strings.Split(r.Group, "/") {
|
|
if !lowerName.MatchString(part) || gotoken.Lookup(part).IsKeyword() {
|
|
return nil, fmt.Errorf("invalid lowerCamelCase group %q", r.Group)
|
|
}
|
|
}
|
|
h := r.Group + "/" + strings.ToLower(r.Handler)
|
|
if handlers[h] {
|
|
return nil, fmt.Errorf("duplicate handler %s in group %s", r.Handler, r.Group)
|
|
}
|
|
handlers[h] = true
|
|
groups[r.Group] = true
|
|
mseen := map[string]bool{}
|
|
for _, m := range r.Middleware {
|
|
if !goName.MatchString(m) || mseen[m] {
|
|
return nil, fmt.Errorf("invalid or duplicate middleware %q", m)
|
|
}
|
|
mseen[m] = true
|
|
if strings.EqualFold(m, "defaults") || strings.EqualFold(m, "registryGen") {
|
|
return nil, fmt.Errorf("reserved middleware name %q", m)
|
|
}
|
|
if prior, ok := middlewareSymbols[strings.ToLower(m)]; ok && prior != m {
|
|
return nil, fmt.Errorf("middleware names %s and %s collide", prior, m)
|
|
}
|
|
middlewareSymbols[strings.ToLower(m)] = m
|
|
}
|
|
shape, err := routeShape(r.Path)
|
|
if err != nil {
|
|
return nil, fmt.Errorf("%s: %w", r.Position, err)
|
|
}
|
|
for _, prior := range spec.Routes {
|
|
if prior.Method != r.Method || prior.Path == r.Path {
|
|
continue
|
|
}
|
|
if conflictPrefix(prior.Path, r.Path) {
|
|
return nil, fmt.Errorf("conflicting parameter names at a shared route prefix: %s and %s", prior.Path, r.Path)
|
|
}
|
|
}
|
|
if prior, exists := shapes[shape]; exists && prior != r.Path {
|
|
return nil, fmt.Errorf("ambiguous route parameter names: %s and %s", prior, r.Path)
|
|
}
|
|
shapes[shape] = r.Path
|
|
pathKey := r.Method + " " + shape
|
|
if paths[pathKey] {
|
|
return nil, fmt.Errorf("duplicate route %s", pathKey)
|
|
}
|
|
paths[pathKey] = true
|
|
if r.Path == "/health/live" || r.Path == "/health/ready" || r.Path == "/openapi.json" {
|
|
return nil, fmt.Errorf("route %s is reserved by the generated server", r.Path)
|
|
}
|
|
if r.Method != strings.ToLower(r.Method) {
|
|
return nil, errors.New("HTTP methods must be lowercase")
|
|
}
|
|
if r.Status != 200 && r.Status != 201 && r.Status != 202 && r.Status != 204 {
|
|
return nil, errors.New("@status supports 200, 201, 202 or 204")
|
|
}
|
|
if !r.Manual && (r.Status == 204) != (r.Response == "") {
|
|
return nil, errors.New("204 requires no response; other success statuses require a response type")
|
|
}
|
|
if r.Method == "head" && r.Response != "" {
|
|
return nil, errors.New("HEAD must not declare a response body")
|
|
}
|
|
if err := validateRouteExtensions(r); err != nil {
|
|
return nil, fmt.Errorf("%s: %w", r.Position, err)
|
|
}
|
|
op := openapi.Operation{Method: r.Method, Path: r.Path, OperationID: operationID(r), Summary: r.Summary, Responses: map[int]openapi.Response{}}
|
|
if r.Request != "" {
|
|
b, ok := c.Bindings[r.Request]
|
|
if !ok {
|
|
return nil, fmt.Errorf("unknown request %s", r.Request)
|
|
}
|
|
op.Parameters = b.Parameters()
|
|
op.Request = b.BodySchema()
|
|
if op.Request != nil && (r.BodyMode == "raw" || r.BodyMode == "multipart") {
|
|
return nil, errors.New("raw/multipart request DTOs may declare only path/form/header fields; body binding is manual")
|
|
}
|
|
if op.Request != nil && (r.Method == "get" || r.Method == "head") {
|
|
return nil, errors.New("GET/HEAD requests cannot declare JSON bodies; use form/path/header tags")
|
|
}
|
|
}
|
|
var response *openapi.Schema
|
|
if r.Response != "" {
|
|
b, ok := c.Bindings[r.Response]
|
|
if !ok {
|
|
return nil, fmt.Errorf("unknown response %s", r.Response)
|
|
}
|
|
s, err := b.ResponseSchema()
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
if r.ResponseFormat == "raw" {
|
|
response = s
|
|
} else {
|
|
response, err = openapi.EnvelopeWith(s, responseConfig(spec, r))
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
}
|
|
}
|
|
op.Responses[r.Status] = openapi.Response{Description: "Success", Schema: response}
|
|
errorSchema, err := openapi.EnvelopeWith(nil, responseConfig(spec, r))
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
for _, code := range []int{400, 413, 415, 500, 501} {
|
|
op.Responses[code] = openapi.Response{Description: "Error", Schema: errorSchema}
|
|
}
|
|
if err = api.Handle(discardRoutes{}, op, func(*httpx.Context) error { return nil }); err != nil {
|
|
return nil, fmt.Errorf("%s: %w", r.Position, err)
|
|
}
|
|
}
|
|
for group := range groups {
|
|
c.Groups = append(c.Groups, group)
|
|
}
|
|
sort.Strings(c.Groups)
|
|
c.Document, err = api.JSON()
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
// Decorate the document with explicit auth/error contracts. Credential
|
|
// validation remains in the linked application middleware.
|
|
var doc map[string]any
|
|
decoder := json.NewDecoder(bytes.NewReader(c.Document))
|
|
decoder.UseNumber()
|
|
if err = decoder.Decode(&doc); err != nil {
|
|
return nil, err
|
|
}
|
|
decorateDocument(doc, spec)
|
|
c.Document, err = json.MarshalIndent(doc, "", " ")
|
|
return c, err
|
|
}
|
|
|
|
type discardRoutes struct{}
|
|
|
|
func (discardRoutes) Handle(string, string, httpx.Handler, ...httpx.Middleware) {}
|
|
func operationID(r Route) string {
|
|
return strings.ReplaceAll(r.Group, "/", "_") + "_" + upper(r.Handler)
|
|
}
|
|
func upper(s string) string { return strings.ToUpper(s[:1]) + s[1:] }
|
|
func lower(s string) string { return strings.ToLower(s[:1]) + s[1:] }
|
|
func routeShape(path string) (string, error) {
|
|
if path == "/" {
|
|
return path, nil
|
|
}
|
|
if !strings.HasPrefix(path, "/") {
|
|
return "", errors.New("route must start with /")
|
|
}
|
|
parts := strings.Split(path[1:], "/")
|
|
seen := map[string]bool{}
|
|
for i, part := range parts {
|
|
if strings.HasPrefix(part, ":") {
|
|
name := part[1:]
|
|
if !lowerName.MatchString(name) || seen[name] {
|
|
return "", errors.New("invalid/duplicate path parameter")
|
|
}
|
|
seen[name] = true
|
|
parts[i] = ":"
|
|
} else if !staticSegment.MatchString(part) || part == "." || part == ".." {
|
|
return "", errors.New("invalid route segment")
|
|
}
|
|
}
|
|
return "/" + strings.Join(parts, "/"), nil
|
|
}
|
|
|
|
func conflictPrefix(left, right string) bool {
|
|
a, b := strings.Split(left, "/"), strings.Split(right, "/")
|
|
for i := 0; i < len(a) && i < len(b); i++ {
|
|
if strings.HasPrefix(a[i], ":") && strings.HasPrefix(b[i], ":") {
|
|
if a[i] != b[i] {
|
|
return true
|
|
}
|
|
continue
|
|
}
|
|
if a[i] != b[i] {
|
|
return false
|
|
}
|
|
}
|
|
return false
|
|
}
|