mirror of
https://github.com/hanzoai/ai.git
synced 2026-11-20 14:13:23 +00:00
471 lines
16 KiB
Go
471 lines
16 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 (
|
|
"encoding/json"
|
|
"reflect"
|
|
"strconv"
|
|
"strings"
|
|
"time"
|
|
"unicode"
|
|
|
|
"github.com/hanzoai/ai/controllers"
|
|
)
|
|
|
|
// The envelope told the truth and said nothing.
|
|
//
|
|
// Every operation here answers {status,msg,data,data2}, and that IS the shape —
|
|
// it is not a placeholder. But `data` carried a sentence where a type belongs
|
|
// ("The operation's own result."), so a reader who wanted the RESULT learned
|
|
// only that there was one. Two hundred operations shared that single sentence,
|
|
// which is why the fleet document counted them all as typed and every generated
|
|
// client handed back an untyped bag.
|
|
//
|
|
// The result's shape was never missing — it is the Go struct the handler already
|
|
// returns, with the json tags it already carries. So it is READ, not written:
|
|
// [shape] reflects a value into a schema, [components] collects the ones the
|
|
// resource table names, and the operation says which of them lands in `data`.
|
|
// Adding a field to object.Store changes the published contract in the same
|
|
// commit, because there is no second place to forget.
|
|
|
|
// shape is the OpenAPI schema of a Go value, read from its type.
|
|
//
|
|
// It follows json tags because those are what reaches the wire: a field tagged
|
|
// `json:"-"` is not in the response and must not be in the document, and an
|
|
// embedded struct's fields belong to the parent exactly as encoding/json flattens
|
|
// them. Cycles terminate at the $ref, since a named type refers to its component
|
|
// rather than expanding a second copy.
|
|
func shape(t reflect.Type, named map[string]reflect.Type) map[string]any {
|
|
for t.Kind() == reflect.Pointer {
|
|
t = t.Elem()
|
|
}
|
|
|
|
// time.Time marshals as an RFC 3339 string, not as its struct fields. Reading
|
|
// the fields would publish wall/ext/loc, which no client has ever seen.
|
|
if t == reflect.TypeFor[time.Time]() {
|
|
return map[string]any{"type": "string", "format": "date-time"}
|
|
}
|
|
|
|
// json.RawMessage is JSON the handler keeps as written — a string, an array,
|
|
// an object. Its kind is a byte slice, which the case below would publish as
|
|
// base64, a shape no caller sends.
|
|
if t == reflect.TypeFor[json.RawMessage]() {
|
|
return map[string]any{}
|
|
}
|
|
|
|
// A type that reflection cannot read states its own schema: JSON kept as
|
|
// written that is still one of a few kinds, or a value that is one of several
|
|
// shapes named by a field.
|
|
if t.Kind() != reflect.Interface {
|
|
switch v := reflect.Zero(t).Interface().(type) {
|
|
case interface{ Schema() map[string]any }:
|
|
return v.Schema()
|
|
case interface{ Variants() (string, []any) }:
|
|
return variants(v, named)
|
|
}
|
|
}
|
|
|
|
switch t.Kind() {
|
|
case reflect.Bool:
|
|
return map[string]any{"type": "boolean"}
|
|
case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64,
|
|
reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64:
|
|
return map[string]any{"type": "integer"}
|
|
case reflect.Float32, reflect.Float64:
|
|
return map[string]any{"type": "number"}
|
|
case reflect.String:
|
|
return map[string]any{"type": "string"}
|
|
case reflect.Slice, reflect.Array:
|
|
// []byte marshals base64, as a string — not as an array of numbers.
|
|
if t.Elem().Kind() == reflect.Uint8 {
|
|
return map[string]any{"type": "string", "format": "byte"}
|
|
}
|
|
return map[string]any{"type": "array", "items": ref(t.Elem(), named)}
|
|
case reflect.Map:
|
|
return map[string]any{"type": "object", "additionalProperties": ref(t.Elem(), named)}
|
|
case reflect.Struct:
|
|
props := map[string]any{}
|
|
out := map[string]any{"type": "object", "properties": props}
|
|
if required := fields(t, props, named); len(required) > 0 {
|
|
out["required"] = required
|
|
}
|
|
return out
|
|
}
|
|
// Interfaces and anything else carry no declared shape. An empty schema says
|
|
// "any JSON", which is the honest answer rather than a guessed one.
|
|
return map[string]any{}
|
|
}
|
|
|
|
// fields writes t's exported fields into props, flattening embedded structs the
|
|
// way encoding/json does, and returns the ones a body must carry.
|
|
//
|
|
// What a field promises beyond its type is read from its tags, in the vocabulary
|
|
// zip's typed handlers already publish with: `validate:"required"` names a field
|
|
// the body must carry, `validate:"min=N,max=N"` bounds a map's entries, a slice's
|
|
// items or a string's length, and `enum:"a,b"` lists the values a string takes.
|
|
func fields(t reflect.Type, props map[string]any, named map[string]reflect.Type) (required []any) {
|
|
for f := range t.Fields() {
|
|
if !f.IsExported() {
|
|
continue
|
|
}
|
|
tag := f.Tag.Get("json")
|
|
name, _, _ := strings.Cut(tag, ",")
|
|
if name == "-" {
|
|
continue
|
|
}
|
|
if f.Anonymous && name == "" {
|
|
e := f.Type
|
|
for e.Kind() == reflect.Pointer {
|
|
e = e.Elem()
|
|
}
|
|
if e.Kind() == reflect.Struct {
|
|
required = append(required, fields(e, props, named)...)
|
|
continue
|
|
}
|
|
}
|
|
if name == "" {
|
|
name = f.Name
|
|
}
|
|
fs := ref(f.Type, named)
|
|
if _, isRef := fs["$ref"]; !isRef {
|
|
bound(fs, f)
|
|
}
|
|
props[name] = fs
|
|
for rule := range strings.SplitSeq(f.Tag.Get("validate"), ",") {
|
|
if rule == "required" {
|
|
required = append(required, name)
|
|
}
|
|
}
|
|
}
|
|
return required
|
|
}
|
|
|
|
// bound writes a field's enum and its min and max into its schema, under the
|
|
// keyword each kind of value takes them by.
|
|
func bound(fs map[string]any, f reflect.StructField) {
|
|
if e := f.Tag.Get("enum"); e != "" {
|
|
var vals []any
|
|
for v := range strings.SplitSeq(e, ",") {
|
|
vals = append(vals, v)
|
|
}
|
|
fs["enum"] = vals
|
|
}
|
|
var min, max string
|
|
switch fs["type"] {
|
|
case "object":
|
|
min, max = "minProperties", "maxProperties"
|
|
case "array":
|
|
min, max = "minItems", "maxItems"
|
|
case "string":
|
|
min, max = "minLength", "maxLength"
|
|
default:
|
|
return
|
|
}
|
|
for rule := range strings.SplitSeq(f.Tag.Get("validate"), ",") {
|
|
key, n, ok := strings.Cut(rule, "=")
|
|
if !ok {
|
|
continue
|
|
}
|
|
v, err := strconv.Atoi(n)
|
|
if err != nil {
|
|
continue
|
|
}
|
|
switch key {
|
|
case "min":
|
|
fs[min] = v
|
|
case "max":
|
|
fs[max] = v
|
|
}
|
|
}
|
|
}
|
|
|
|
// variants is the schema of a value that is one of several shapes, told apart by
|
|
// one field: oneOf the shapes, and the discriminator mapping each shape's value of
|
|
// that field — read from the field's enum — to the shape.
|
|
func variants(v interface{ Variants() (string, []any) }, named map[string]reflect.Type) map[string]any {
|
|
field, shapes := v.Variants()
|
|
var one []any
|
|
mapping := map[string]any{}
|
|
for _, s := range shapes {
|
|
t := reflect.TypeOf(s)
|
|
r := ref(t, named)
|
|
one = append(one, r)
|
|
for f := range t.Fields() {
|
|
name, _, _ := strings.Cut(f.Tag.Get("json"), ",")
|
|
if name == field && f.Tag.Get("enum") != "" && !strings.Contains(f.Tag.Get("enum"), ",") {
|
|
mapping[f.Tag.Get("enum")] = r["$ref"]
|
|
}
|
|
}
|
|
}
|
|
return map[string]any{
|
|
"oneOf": one,
|
|
"discriminator": map[string]any{"propertyName": field, "mapping": mapping},
|
|
}
|
|
}
|
|
|
|
// ref is a $ref when the type has a name worth sharing, and the shape inline
|
|
// when it does not.
|
|
//
|
|
// Sharing matters for more than size: a client that sees object.Provider in two
|
|
// places should get ONE type, not two structurally-identical ones it cannot pass
|
|
// between. Anonymous and builtin types have no name to share, so they inline.
|
|
func ref(t reflect.Type, named map[string]reflect.Type) map[string]any {
|
|
e := t
|
|
for e.Kind() == reflect.Pointer {
|
|
e = e.Elem()
|
|
}
|
|
if e.Kind() == reflect.Struct && e.Name() != "" && e != reflect.TypeFor[time.Time]() {
|
|
n := component(e)
|
|
named[n] = e
|
|
return map[string]any{"$ref": "#/components/schemas/" + n}
|
|
}
|
|
return shape(e, named)
|
|
}
|
|
|
|
// component is the document's name for a type: its Go name, qualified by the
|
|
// package it lives in when that package is not object.
|
|
//
|
|
// object is unqualified because it holds the nouns this service is about — a
|
|
// reader seeing "Store" in an ai document does not need to be told which Store.
|
|
func component(t reflect.Type) string {
|
|
name := exported(t.Name())
|
|
pkg := t.PkgPath()
|
|
if i := strings.LastIndex(pkg, "/"); i >= 0 {
|
|
pkg = pkg[i+1:]
|
|
}
|
|
if n, ok := shortPkg[pkg]; ok {
|
|
pkg = n
|
|
}
|
|
if pkg == "" || pkg == "object" {
|
|
if n, ok := published[name]; ok {
|
|
return n
|
|
}
|
|
return name
|
|
}
|
|
return pkg + "." + name
|
|
}
|
|
|
|
// shortPkg is the name a package is KNOWN by, where the last segment of its
|
|
// import path is not it.
|
|
//
|
|
// A schema name reaches every generated SDK as a class name, so it has to be a
|
|
// legal identifier in nine languages. "go-openai" is a repository name and it
|
|
// carries a hyphen, which is not; "openai" is what the package calls itself and
|
|
// what a reader of the wire format already knows.
|
|
//
|
|
// controllers is where this service's handlers live, which is a fact about this
|
|
// repository's layout and not about the API. A client holding one of these types
|
|
// is holding an ai shape, so that is the word it is published under.
|
|
var shortPkg = map[string]string{
|
|
"go-openai": "openai",
|
|
"controllers": "ai",
|
|
}
|
|
|
|
// exported is a type's name as a schema name.
|
|
//
|
|
// An unexported Go type is unexported to this repository, not to the wire: the
|
|
// shape crosses either way, and a generator asked for a class named modelList
|
|
// either lowercases a class or, in a language with no such convention, emits
|
|
// something a reader cannot connect to the ModelList in the document.
|
|
func exported(name string) string {
|
|
if name == "" {
|
|
return ""
|
|
}
|
|
r := []rune(name)
|
|
r[0] = unicode.ToUpper(r[0])
|
|
return string(r)
|
|
}
|
|
|
|
// published is the wire name for a type whose Go name is a word another product
|
|
// in the fleet already means something else by.
|
|
//
|
|
// hanzoai/cloud composes this document with ~180 others into ONE flat set of
|
|
// schema names and refuses a name that carries two shapes, so a word here is
|
|
// claimed fleet-wide, not per-service. Both of these lose the argument on
|
|
// accuracy rather than seniority:
|
|
//
|
|
// Record is {name, type, value} in platform and projects — a DNS record, which
|
|
// is exactly what that word means. This one is {id, owner, organization,
|
|
// clientIp}: who reached what, from where. That is an audit trail.
|
|
//
|
|
// Usage is {cpuNs, rssBytes, threads, fds} in the plugin supervisor — what a
|
|
// process is consuming right now. This one is {date, userCount, chatCount,
|
|
// tokenCount, price}: a day's counts, priced. That is a tally.
|
|
//
|
|
// Only the WIRE name moves. object.Record and object.Usage keep their Go names,
|
|
// because renaming a Go type to settle a document is the tail wagging the dog.
|
|
var published = map[string]string{
|
|
"Record": "Audit",
|
|
|
|
// Five more, all settled the same way and all settled on accuracy. Each of
|
|
// these names was already claimed by a shape a published client is bound to,
|
|
// and ours arrived today — so ours is the one that is still free to be right.
|
|
//
|
|
// Usage is {date, userCount, chatCount, tokenCount, price} — a day's counts,
|
|
// priced. affiliate's is money owed and money paid. Ours counts.
|
|
//
|
|
// Application is a Template plus parameters, deployed and served. affiliate's
|
|
// is somebody asking to join a programme. Ours is a program.
|
|
//
|
|
// Scan is {targetMode, target, asset} — a job that goes and looks. security's
|
|
// is {content, path}, one file that was looked at.
|
|
//
|
|
// Suggestion is {text, isHit} — a string offered while typing, flagged if it
|
|
// matched. guide's is a recommended action with a rationale.
|
|
//
|
|
// Form is {formItems, position, category, url} — how a page is laid out.
|
|
// company's is a document with a signature on it.
|
|
"Usage": "Count",
|
|
"Application": "App",
|
|
"Scan": "Sweep",
|
|
"Suggestion": "Candidate",
|
|
"Form": "Layout",
|
|
}
|
|
|
|
// components is every schema the document refers to, closed over its own
|
|
// references: reflecting Store names Provider, reflecting Provider names
|
|
// whatever Provider holds, and so on until nothing new appears.
|
|
func components(roots []reflect.Type, named map[string]reflect.Type) map[string]any {
|
|
for _, t := range roots {
|
|
named[component(t)] = t
|
|
}
|
|
out := map[string]any{}
|
|
for len(out) != len(named) {
|
|
for n, t := range named {
|
|
if _, done := out[n]; done {
|
|
continue
|
|
}
|
|
// shape may add to named; the loop runs again until it stops growing.
|
|
out[n] = shape(t, named)
|
|
break
|
|
}
|
|
}
|
|
return out
|
|
}
|
|
|
|
// result is the envelope with `data` narrowed to what THIS operation returns.
|
|
//
|
|
// It is allOf rather than a rewritten envelope so the two facts stay separate:
|
|
// the envelope is the surface's contract and lives in one place, and the data
|
|
// shape is the operation's own. A generator that understands allOf gets both; one
|
|
// that does not still sees the envelope.
|
|
func result(data map[string]any) map[string]any {
|
|
return map[string]any{
|
|
"allOf": []any{
|
|
map[string]any{"$ref": "#/components/schemas/Envelope"},
|
|
map[string]any{
|
|
"type": "object",
|
|
"properties": map[string]any{"data": data},
|
|
},
|
|
},
|
|
}
|
|
}
|
|
|
|
// answer is the Responses Object for a hand-written route, built from the Go
|
|
// value its handler writes.
|
|
//
|
|
// Every named struct becomes a $ref, at the root and inside it, because sharing
|
|
// is the point: object.Memory answers five of these operations and a client
|
|
// should get ONE type it can pass between them, not five structurally identical
|
|
// ones it cannot. A slice or a map has no name to share and inlines.
|
|
//
|
|
// 401 and 403 are stated for the same reason [op] states them: refusal is part of
|
|
// the contract, and a client generated from a document that names only the happy
|
|
// answer has nowhere to put the other one.
|
|
func answer(a controllers.Answer, named map[string]reflect.Type) map[string]any {
|
|
s := ref(reflect.TypeOf(a.Shape), named)
|
|
if a.Data {
|
|
s = result(s)
|
|
}
|
|
out := map[string]any{
|
|
"200": map[string]any{
|
|
"description": "Success.",
|
|
"content": map[string]any{"application/json": map[string]any{"schema": s}},
|
|
},
|
|
"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."},
|
|
}
|
|
for status, r := range a.Refusals {
|
|
entry := map[string]any{
|
|
"description": r.Says,
|
|
"content": map[string]any{"application/json": map[string]any{"schema": ref(reflect.TypeOf(r.Shape), named)}},
|
|
}
|
|
if r.Wait {
|
|
entry["headers"] = map[string]any{
|
|
"Retry-After": map[string]any{
|
|
"description": "Seconds to wait before asking again.",
|
|
"schema": map[string]any{"type": "integer"},
|
|
},
|
|
"Retry-After-Ms": map[string]any{
|
|
"description": "Milliseconds to wait before asking again.",
|
|
"schema": map[string]any{"type": "integer"},
|
|
},
|
|
}
|
|
}
|
|
out[strconv.Itoa(status)] = entry
|
|
}
|
|
if a.Traced {
|
|
for _, e := range out {
|
|
entry := e.(map[string]any)
|
|
headers, _ := entry["headers"].(map[string]any)
|
|
if headers == nil {
|
|
headers = map[string]any{}
|
|
entry["headers"] = headers
|
|
}
|
|
headers["X-Request-Id"] = map[string]any{
|
|
"description": "The id this answer is filed under: the caller's own X-Request-Id, or a fresh one.",
|
|
"schema": map[string]any{"type": "string"},
|
|
}
|
|
}
|
|
}
|
|
return out
|
|
}
|
|
|
|
// take is the Request Body Object for a hand-written route, built from the Go
|
|
// value its handler decodes — the request half of [answer], with the same
|
|
// sharing: a named struct is a $ref.
|
|
func take(v any, named map[string]reflect.Type) map[string]any {
|
|
return map[string]any{
|
|
"required": true,
|
|
"content": map[string]any{"application/json": map[string]any{"schema": ref(reflect.TypeOf(v), named)}},
|
|
}
|
|
}
|
|
|
|
// listOf and oneOf are what a collection and a member put in `data`.
|
|
func listOf(t reflect.Type) map[string]any {
|
|
return map[string]any{"type": "array", "items": map[string]any{"$ref": "#/components/schemas/" + component(t)}}
|
|
}
|
|
|
|
func oneOf(t reflect.Type) map[string]any {
|
|
return map[string]any{"$ref": "#/components/schemas/" + component(t)}
|
|
}
|
|
|
|
// product is the noun a path belongs to: the segment after the version.
|
|
//
|
|
// /v1/ai/stores is "ai", /v1/chat/completions is "chat". It is the same cut
|
|
// hanzoai/cloud makes when it groups the fleet, and stating it here is what lets
|
|
// an operation of ours be counted under the product it actually serves.
|
|
func product(path string) string {
|
|
seg := strings.Split(strings.TrimPrefix(path, "/"), "/")
|
|
if len(seg) >= 2 && strings.HasPrefix(seg[0], "v") {
|
|
return seg[1]
|
|
}
|
|
if len(seg) >= 1 {
|
|
return seg[0]
|
|
}
|
|
return ""
|
|
}
|