Documentation
¶
Overview ¶
Package modelref parses the catalog reference DSL used by Policy grants and the /catalog/resolve admin endpoint.
Grammar — five shapes, no wildcards in the wire form. Absence of a segment is the wildcard:
ref ::= provider "anthropic" all anthropic models, all hosts
| provider "@" host "anthropic@bedrock" all anthropic models, only on bedrock
| provider "/" model "anthropic/claude-opus-4-7" this model on any host
| provider "/" model "@" host "anthropic/claude-opus-4-7@bedrock" this exact binding only
| "@" host "@bedrock" every model on this host
Slugs follow DNS-1123 (matches meta.Metadata.Name validation): lower alphanumerics + hyphen, max 63 chars, must start and end with an alphanumeric.
Index ¶
- Variables
- func Format(provider, model, host string) (string, error)
- func Includes(outer, inner Ref) bool
- func MatchAny(refs []string, providerSlug, modelSlug, hostSlug string) bool
- func Overlap(a, b Ref) bool
- func Resolve(refs []Ref, catalog []ConcreteBinding) map[string][]ConcreteBinding
- func Specificity(r Ref) int
- func Validate(s string) error
- type Carveout
- type ConcreteBinding
- type Conflict
- type Group
- type Kind
- type Ref
- type SyntaxError
Constants ¶
This section is empty.
Variables ¶
var ( // ErrEmpty is returned for an empty input string. ErrEmpty = errors.New("modelref: empty ref") )
Functions ¶
func Format ¶
Format builds the canonical shortest ref form for the given segments. Empty string means "wildcard / absent" on that axis.
func Includes ¶
Includes reports whether every concrete binding that satisfies inner also satisfies outer.
func MatchAny ¶
Matches reports whether this Ref allows the (provider, model, host) binding triple. All three inputs are catalog slugs (Meta.Name). Each wildcard bit independently relaxes the corresponding equality check.
Used by the routing resolver to decide whether a candidate HostBinding is allowed by the caller's Policy. MatchAny reports whether any ref string in refs matches the given (provider, model, host) triple. Refs that fail to parse are skipped silently — Validate rejects malformed refs at write time, so a bad ref reaching here means hand-edited data; ignoring is safer than erroring at request time.
func Overlap ¶
Overlap reports whether some concrete binding could satisfy both refs. Per-axis: if both refs name a value, they must agree; wildcards always pass.
func Resolve ¶
func Resolve(refs []Ref, catalog []ConcreteBinding) map[string][]ConcreteBinding
Resolve expands each ref against catalog. Map key is ref.Raw; value is the bindings that ref covers (in catalog order).
func Specificity ¶
Specificity scores a ref. Higher = more specific = wins ties when two refs both cover the same binding. Host-anchoring beats model-anchoring at equal segment counts (host is the credentials/billing boundary).
Types ¶
type Carveout ¶
type Carveout[O comparable] struct { Binding ConcreteBinding Winner O Losers []O }
Carveout records a binding that more than one owner could have claimed. Winner is the assigned owner; Losers are the other owners that also covered it (in declared order).
func AssignSpecificityWins ¶
func AssignSpecificityWins[O comparable](groups []Group[O], catalog []ConcreteBinding) (map[O][]ConcreteBinding, []Carveout[O])
AssignSpecificityWins attributes each binding in catalog to one owner using ref specificity. Per binding:
- Each group's score for this binding = max Specificity over its covering refs (groups with no covering ref are skipped).
- Winner = group with highest score; ties broken by groups order.
- If more than one group qualified, the binding is also recorded as a Carveout listing the losers.
assignments maps every input owner (even those with zero bindings) to its owned bindings, in catalog order.
type ConcreteBinding ¶
ConcreteBinding is a fully-qualified (provider, model, host) triple. Used by Overlap*/Resolve/Assign helpers as the catalog index.
func OverlappingBindings ¶
func OverlappingBindings(a, b Ref, catalog []ConcreteBinding) []ConcreteBinding
OverlappingBindings returns every binding in catalog covered by BOTH refs. Returns nil (not empty) when refs are conceptually disjoint.
func (ConcreteBinding) String ¶
func (b ConcreteBinding) String() string
type Conflict ¶
type Conflict[O comparable] struct { Binding ConcreteBinding Winner O Losers []O }
Conflict mirrors Carveout for AssignFirstWins. Same fields, different resolution rule.
func AssignFirstWins ¶
func AssignFirstWins[O comparable](groups []Group[O], catalog []ConcreteBinding) (map[O][]ConcreteBinding, []Conflict[O])
AssignFirstWins is the simpler attribution: each binding goes to the first group (in declared order) that covers it. Conflicts list the bindings that more than one group could have claimed.
type Group ¶
type Group[O comparable] struct { Owner O Refs []Ref }
Group binds an owner identity to a list of refs the owner declares. Used by Assign* helpers to attribute concrete bindings to owners.
type Kind ¶
type Kind string
Kind classifies a Ref for the resolve API response.
const ( KindProvider Kind = "provider" // provider — all models, all hosts KindProviderOnHost Kind = "provider-on-host" // provider@host — all models, single host KindModel Kind = "model" // provider/model — single model, all hosts KindBinding Kind = "binding" // provider/model@host — single binding KindHost Kind = "host" // @host — all providers, all models, single host )
type Ref ¶
type Ref struct {
Raw string
// Provider is the provider slug. "" when ProviderWildcard is true
// (host-only refs of the form "@host").
Provider string
// Model is the model slug, "" when ModelWildcard is true.
Model string
// Host is the host slug, "" when HostWildcard is true.
Host string
// ProviderWildcard is true for host-only refs ("@bedrock"). False
// for every other shape.
ProviderWildcard bool
// ModelWildcard is true when the model position is "*" or absent.
ModelWildcard bool
// HostWildcard is true when the host position is "*" or absent.
HostWildcard bool
}
Ref is the parsed form of a ref string. The string itself is preserved in Raw so admin UIs can echo it verbatim alongside the expansion.
func MustParse ¶
MustParse is the panic-on-error variant used by tests and seeds where the ref is hard-coded and a parse failure is a build error.
func Parse ¶
Parse turns a ref string into a Ref. Returns ErrEmpty on "" and *SyntaxError on a malformed input. The parser never touches the catalog — it only enforces grammar.
Each segment (provider, model, host) is slug-normalized via pkg/slug before matching, so authors can paste real-world names (e.g. "openai/gpt-5.5") and the ref resolves against the catalog's slug form ("openai/gpt-5-5"). The `/` and `@` separators are structural and never normalized away.
func (Ref) Covers ¶
func (r Ref) Covers(b ConcreteBinding) bool
Covers reports whether r grants binding b. Each defined segment must match; wildcard segments pass.
type SyntaxError ¶
SyntaxError describes a malformed ref. Carries the raw input + a human-friendly explanation suitable for surfacing in 400 responses.
func (*SyntaxError) Error ¶
func (e *SyntaxError) Error() string
Source Files