mirror of
https://github.com/hanzoai/ai.git
synced 2026-11-21 11:09:56 +00:00
The resource table names a shape for every generated operation and
routers/shape.go reflects it into the published document. The hand-written
half had no equivalent, so 91 operations reached the fleet document with no
response at all — /v1/models, /v1/chat/completions, /v1/embeddings,
/v1/messages, every address a client actually calls. Generated SDKs handed
those back as an untyped bag.
controllers.Answers is that missing half: one table, handler to the Go value
its body is. It lives in controllers because most of these shapes are
unexported there, so a table in routers could not name them at all. Two
constructors name the surface's two real dialects — data() for the
{status,msg,data} envelope, whole() for an OpenAI- or Anthropic-compatible
body. A handler that is absent answers a stream, an audio or video body, or
a redirect, which has no JSON shape; absent is the honest word for that.
Four bodies were built as map literals, so they had no type to reflect and
now do: modelList, videoStatus, ranking, tokenCount. The video projection
test asks the marshalled JSON for the upstream id instead of ranging the
map's top level, which also covers nested fields.
Named structs $ref at the root as well as inside it, so the five operations
answering object.Memory hand a client one type it can pass between them.
420 lines
15 KiB
Go
420 lines
15 KiB
Go
// Copyright 2023-2026 Hanzo AI Inc. All Rights Reserved.
|
|
//
|
|
// Licensed under the Apache License, Version 2.0 (the "License");
|
|
// you may not use this file except in compliance with the License.
|
|
// You may obtain a copy of the License at
|
|
//
|
|
// http://www.apache.org/licenses/LICENSE-2.0
|
|
//
|
|
// Unless required by applicable law or agreed to in writing, software
|
|
// distributed under the License is distributed on an "AS IS" BASIS,
|
|
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
// See the License for the specific language governing permissions and
|
|
// limitations under the License.
|
|
|
|
package routers
|
|
|
|
import (
|
|
"reflect"
|
|
"strings"
|
|
|
|
"github.com/zap-proto/zip"
|
|
|
|
"github.com/hanzoai/ai/controllers"
|
|
)
|
|
|
|
// The published API description of this service is DERIVED from the router that
|
|
// serves it — never written a second time.
|
|
//
|
|
// A hand-maintained spec beside a route table is two sources for one fact, and
|
|
// they drift in the direction that hurts: the spec is what customers and every
|
|
// generated SDK believe, so it goes stale silently while the routes move. The
|
|
// checked-in swagger.json in this repo is the standing proof — it still describes
|
|
// `/api/<verb>-<noun>`, a base path this service has never served.
|
|
//
|
|
// So [Document] is the ONE accessor, and it is a whole document rather than a
|
|
// fragment somebody else completes. hanzoai/cloud reaches this surface through a
|
|
// single `/v1/*` entry point and publishes what comes back as the fleet's contract,
|
|
// so what it asks for is everything an operation owes a reader: the address, the
|
|
// verb, the sentence, and — where this service declares one — the body.
|
|
//
|
|
// Membership comes from [App.Patterns], the live route table, because that is
|
|
// the only thing that knows what answers. Detail comes from wherever it is
|
|
// already written: the resource table for the half it generates, the doc comment
|
|
// on the handler for the rest. Nothing is copied.
|
|
|
|
// Document is everything this service serves, as one OpenAPI 3.1 document.
|
|
//
|
|
// The result is deterministic: it reads the route table and two package-level
|
|
// tables, and nothing here reads the clock, the environment, or a random source.
|
|
func Document(app *zip.App) map[string]any {
|
|
described := items()
|
|
said := map[string]Doc{}
|
|
// Every named type the document ends up referring to, gathered as the paths are
|
|
// built rather than from a list beside them, so a shape cannot be published
|
|
// without its components.
|
|
named := map[string]reflect.Type{}
|
|
answered := map[string]map[string]any{}
|
|
for _, w := range wired {
|
|
path := openAPIPath(w.Path)
|
|
said[w.Method+" "+path] = Doc{Summary: w.Summary, Description: w.Description}
|
|
if a, ok := controllers.Answers()[w.Handler]; ok {
|
|
answered[w.Method+" "+path] = answer(a, named)
|
|
}
|
|
}
|
|
|
|
paths := map[string]any{}
|
|
for pattern, methods := range Patterns(app) {
|
|
path := openAPIPath(pattern)
|
|
for _, registered := range methods {
|
|
for _, verb := range expand(registered) {
|
|
item, ok := paths[path].(map[string]any)
|
|
if !ok {
|
|
item = map[string]any{}
|
|
paths[path] = item
|
|
}
|
|
generated, _ := described[path].(map[string]any)
|
|
o, _ := generated[strings.ToLower(verb)].(map[string]any)
|
|
if o == nil {
|
|
// A hand-written route. Its body is the OpenAI wire format or a
|
|
// stream, not this service's envelope, so the only honest thing
|
|
// to say about it is what its handler says.
|
|
o = map[string]any{}
|
|
}
|
|
d, ok := said[verb+" "+path]
|
|
if !ok {
|
|
// One handler answering every verb says one thing about all of
|
|
// them, and the table keeps the star it was registered under.
|
|
d = said["* "+path]
|
|
}
|
|
if d.Summary != "" {
|
|
o["summary"] = d.Summary
|
|
}
|
|
if d.Description != "" {
|
|
o["description"] = d.Description
|
|
}
|
|
// A hand-written route's own body. Only where the generated half said
|
|
// nothing: an operation the resource table describes is described by
|
|
// the table, and this cannot overrule it.
|
|
if _, told := o["responses"]; !told {
|
|
r, ok := answered[verb+" "+path]
|
|
if !ok {
|
|
r = answered["* "+path]
|
|
}
|
|
if r != nil {
|
|
o["responses"] = r
|
|
}
|
|
}
|
|
// Named HERE because this is the one place that knows both the verb
|
|
// and the address. items() builds operations before it knows which
|
|
// verbs the router actually registered for them.
|
|
o["operationId"] = zip.ID(verb, path)
|
|
// The PRODUCT this operation belongs to. hanzoai/cloud counts a
|
|
// product by the tags its operations carry, so an untagged operation
|
|
// belongs to nothing: it reaches the composed document and then
|
|
// disappears from every per-product total, which is how a surface
|
|
// loses whole products with the path count unchanged.
|
|
if t := product(path); t != "" {
|
|
o["tags"] = []any{t}
|
|
}
|
|
// A templated segment NAMES a parameter, and an operation that
|
|
// leaves it undeclared reaches a client with the value in its
|
|
// address and not in its signature — `get_videos_by_id(self)`
|
|
// took no id and requested the literal "{id}". Merged rather
|
|
// than assigned, so a hand-written list survives.
|
|
if names := pathParams(path); len(names) > 0 {
|
|
params, _ := o["parameters"].([]any)
|
|
have := map[string]bool{}
|
|
for _, p := range params {
|
|
m, ok := p.(map[string]any)
|
|
if !ok || m["in"] != "path" {
|
|
continue
|
|
}
|
|
if n, _ := m["name"].(string); n != "" {
|
|
have[n] = true
|
|
}
|
|
}
|
|
for _, n := range names {
|
|
if have[n] {
|
|
continue
|
|
}
|
|
params = append(params, map[string]any{
|
|
"name": n, "in": "path", "required": true,
|
|
"schema": map[string]any{"type": "string"},
|
|
})
|
|
}
|
|
o["parameters"] = params
|
|
}
|
|
item[strings.ToLower(verb)] = o
|
|
}
|
|
}
|
|
}
|
|
|
|
// Every type the resource table names, closed over what those types refer to.
|
|
// The roots come from the table rather than a list beside it, so a resource
|
|
// cannot publish a shape the document does not carry.
|
|
var roots []reflect.Type
|
|
for _, r := range resources {
|
|
if r.shape != nil {
|
|
roots = append(roots, reflect.TypeOf(r.shape))
|
|
}
|
|
}
|
|
schemas := components(roots, named)
|
|
schemas["Envelope"] = envelope()
|
|
|
|
return map[string]any{
|
|
"openapi": "3.1.0",
|
|
"info": map[string]any{"title": "Hanzo AI", "version": "v1"},
|
|
"paths": paths,
|
|
"components": map[string]any{"schemas": schemas},
|
|
}
|
|
}
|
|
|
|
// expand is the verbs one registration publishes.
|
|
//
|
|
// A route registered "*" is ONE handler answering every method, so the document
|
|
// has to choose which of them to name. It names the five a client calls. TRACE
|
|
// echoes the request back and is the Cross-Site Tracing vector; OPTIONS is CORS
|
|
// preflight, which a browser sends and a person never does — advertising either
|
|
// puts a method in every generated SDK, CLI and tool list that nobody should
|
|
// reach for.
|
|
func expand(registered string) []string {
|
|
all := []string{"DELETE", "GET", "PATCH", "POST", "PUT"}
|
|
if registered == "*" {
|
|
return all
|
|
}
|
|
registered = strings.ToUpper(registered)
|
|
for _, v := range all {
|
|
if v == registered {
|
|
return []string{registered}
|
|
}
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// envelope is the one body this service returns from its resource surface.
|
|
//
|
|
// `data` is left open HERE because the envelope belongs to the surface and the
|
|
// result belongs to the operation: what comes back from listing stores is not
|
|
// what comes back from reading one. Each operation narrows it — see [result] —
|
|
// so the two facts compose instead of one of them having to be vague.
|
|
func envelope() map[string]any {
|
|
return map[string]any{
|
|
"type": "object",
|
|
"required": []any{"status", "msg"},
|
|
"description": "The resource surface's response. `status` is the verdict, not the HTTP code: " +
|
|
"a handled failure is still 200.",
|
|
"properties": map[string]any{
|
|
"status": map[string]any{"type": "string", "enum": []any{"ok", "error"}},
|
|
"msg": map[string]any{"type": "string", "description": "Empty on success, the reason on failure."},
|
|
"data": map[string]any{"description": "The operation's own result."},
|
|
"data2": map[string]any{"description": "A second result the operation defines, when it has one."},
|
|
},
|
|
}
|
|
}
|
|
|
|
// items are the Path Item Objects the resource table generates, keyed by path.
|
|
func items() map[string]any {
|
|
out := map[string]any{}
|
|
|
|
add := func(path, method string, op map[string]any) {
|
|
path = openAPIPath(path)
|
|
item, ok := out[path].(map[string]any)
|
|
if !ok {
|
|
item = map[string]any{}
|
|
out[path] = item
|
|
}
|
|
item[strings.ToLower(method)] = op
|
|
}
|
|
|
|
for _, r := range resources {
|
|
coll, member := r.collection(), r.member()
|
|
// What this resource IS, read off its own row. A row with no shape has not
|
|
// said, and its operations publish the bare envelope as before.
|
|
var list, one map[string]any
|
|
if r.shape != nil {
|
|
t := reflect.TypeOf(r.shape)
|
|
list, one = listOf(t), oneOf(t)
|
|
}
|
|
|
|
if !r.noList {
|
|
add(coll, "GET", op("List "+r.path,
|
|
"List the caller's "+r.path+".", nil, false, list))
|
|
}
|
|
if !r.noCreate {
|
|
add(coll, "POST", op("Create a "+singularNoun(r),
|
|
"Create one "+singularNoun(r)+".", nil, true, one))
|
|
}
|
|
if r.global {
|
|
add(coll+"/global", "GET", op("List "+r.path+" across tenants",
|
|
"Cross-tenant listing. Admin-only; a tenant caller is refused.", nil, false, list))
|
|
}
|
|
|
|
mp := memberParams()
|
|
if !r.noRead {
|
|
add(member, "GET", op("Retrieve a "+singularNoun(r),
|
|
"Read one "+singularNoun(r)+" by its (owner, name) key.", mp, false, one))
|
|
}
|
|
if !r.noUpdate {
|
|
add(member, "PATCH", op("Update a "+singularNoun(r),
|
|
"Update one "+singularNoun(r)+". PATCH and PUT reach the same handler, "+
|
|
"which has always taken a whole object.", mp, true, one))
|
|
add(member, "PUT", op("Replace a "+singularNoun(r),
|
|
"Identical to PATCH — the handler takes a whole object either way.", mp, true, one))
|
|
}
|
|
if !r.noDelete {
|
|
add(member, "DELETE", op("Delete a "+singularNoun(r),
|
|
"Delete one "+singularNoun(r)+".", mp, false, one))
|
|
}
|
|
|
|
for _, a := range r.actions {
|
|
verb := a.verb
|
|
if verb == "" {
|
|
verb = "POST"
|
|
}
|
|
p, params := coll+"/"+a.name, []any(nil)
|
|
if !a.collection {
|
|
p, params = member+"/"+a.name, mp
|
|
}
|
|
body := verb == "POST" || verb == "PUT" || verb == "PATCH"
|
|
add(p, verb, op(actionSummary(a.name, singularNoun(r)), "", params, body, nil))
|
|
}
|
|
}
|
|
|
|
for _, s := range singletons {
|
|
// Iterate a FIXED verb order, not the map: Go randomizes map order, and an
|
|
// accessor whose output reorders between runs cannot be diffed for drift.
|
|
for _, verb := range []string{"GET", "POST", "PUT", "PATCH", "DELETE"} {
|
|
if _, ok := s.verbs[verb]; !ok {
|
|
continue
|
|
}
|
|
body := verb == "POST" || verb == "PUT" || verb == "PATCH"
|
|
add(s.url(), verb, op(actionSummary(s.path, ""), "", nil, body, nil))
|
|
}
|
|
}
|
|
|
|
return out
|
|
}
|
|
|
|
// op builds one Operation Object.
|
|
//
|
|
// Every response is the SAME envelope: this surface answers {status,msg,data,data2}
|
|
// on success AND on a handled failure, so a 200 does not imply success — `status`
|
|
// does. That is a property of the backend, not a description choice, and saying so
|
|
// here is the difference between a spec a client can trust and one that quietly
|
|
// misleads.
|
|
//
|
|
// The refusals are written out rather than pointed at a shared Response Object,
|
|
// because a $ref binds this document to component definitions it does not carry,
|
|
// and an operation pointing at a definition that is not here resolves to nothing.
|
|
// The `data` argument is what THIS operation puts in the envelope's data field.
|
|
// Nil means the operation has not said — the envelope alone, which is what every
|
|
// operation used to publish.
|
|
func op(summary, description string, params []any, body bool, data map[string]any) map[string]any {
|
|
schema := map[string]any{"$ref": "#/components/schemas/Envelope"}
|
|
if data != nil {
|
|
schema = result(data)
|
|
}
|
|
o := map[string]any{
|
|
"summary": summary,
|
|
"responses": map[string]any{
|
|
"200": map[string]any{
|
|
"description": "Envelope. `status` is \"ok\" or \"error\" — check it; a handled " +
|
|
"failure is still HTTP 200.",
|
|
"content": map[string]any{
|
|
"application/json": map[string]any{"schema": schema},
|
|
},
|
|
},
|
|
"401": map[string]any{"description": "No credential, or one this service does not accept."},
|
|
"403": map[string]any{"description": "A valid credential that may not do this."},
|
|
},
|
|
}
|
|
if description != "" {
|
|
o["description"] = description
|
|
}
|
|
if len(params) > 0 {
|
|
o["parameters"] = params
|
|
}
|
|
if body {
|
|
o["requestBody"] = map[string]any{
|
|
"required": true,
|
|
"content": map[string]any{
|
|
"application/json": map[string]any{
|
|
"schema": map[string]any{"type": "object"},
|
|
},
|
|
},
|
|
}
|
|
}
|
|
return o
|
|
}
|
|
|
|
// memberParams are the two segments that identify a member.
|
|
//
|
|
// They are two parameters, not one, because the identity of every object here is
|
|
// the PAIR (owner, name) and a single segment cannot carry it — a composite id
|
|
// URL-encoded into one segment is decoded back to a separator before routing and
|
|
// matches nothing. The spec has to say that or every generated SDK gets it wrong.
|
|
func memberParams() []any {
|
|
return []any{
|
|
map[string]any{
|
|
"name": "owner", "in": "path", "required": true,
|
|
"schema": map[string]any{"type": "string"},
|
|
"description": "Owning organization.",
|
|
},
|
|
map[string]any{
|
|
"name": "name", "in": "path", "required": true,
|
|
"schema": map[string]any{"type": "string"},
|
|
"description": "Resource name, unique within the owner.",
|
|
},
|
|
}
|
|
}
|
|
|
|
// actionSummary renders a URL segment as a human summary: "query-second" ->
|
|
// "Query second", "mcp-tools" -> "Mcp tools".
|
|
func actionSummary(name, subject string) string {
|
|
s := titleCase(strings.ReplaceAll(name, "-", " "))
|
|
if subject != "" {
|
|
return s + " (" + subject + ")"
|
|
}
|
|
return s
|
|
}
|
|
|
|
// openAPIPath rewrites the router's ":name" parameter syntax into OpenAPI's
|
|
// "{name}". The two describe the same route; only the spelling differs, and a
|
|
// spec left in the router's spelling silently produces SDKs that request a
|
|
// literal ":owner".
|
|
func openAPIPath(p string) string {
|
|
segs := strings.Split(p, "/")
|
|
for i, s := range segs {
|
|
if strings.HasPrefix(s, ":") {
|
|
segs[i] = "{" + s[1:] + "}"
|
|
}
|
|
}
|
|
return strings.Join(segs, "/")
|
|
}
|
|
|
|
// pathParams names the templated segments of an OpenAPI path. Rewriting the
|
|
// spelling is only half of what that comment above promises: a client also
|
|
// needs the parameter DECLARED, or the generator emits a method that cannot be
|
|
// given the value its own name asks for.
|
|
func pathParams(p string) []string {
|
|
var names []string
|
|
for _, s := range strings.Split(p, "/") {
|
|
if len(s) > 2 && s[0] == '{' && s[len(s)-1] == '}' {
|
|
names = append(names, s[1:len(s)-1])
|
|
}
|
|
}
|
|
return names
|
|
}
|
|
|
|
func titleCase(s string) string {
|
|
parts := strings.FieldsFunc(s, func(r rune) bool { return r == '-' || r == ' ' || r == '/' })
|
|
for i, p := range parts {
|
|
if p == "" {
|
|
continue
|
|
}
|
|
parts[i] = strings.ToUpper(p[:1]) + p[1:]
|
|
}
|
|
return strings.Join(parts, " ")
|
|
}
|