catalogview

package
v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 2, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Package catalogview builds consumer-facing read projections of catalog data for the admin/UX surface ("API UX"): a model's hosts, its pricing per host, the policies that grant it. These back resource-navigation endpoints (GET /models/{ref}/hosts, .../pricing, .../policies) and, later, ?expand= on the base model read — the same functions serve both.

Source is Postgres (the entity Stores), NOT the in-memory snapshot: detail/UX views intentionally reflect the full persisted state, including disabled rows, the way the CRUD APIs do. This also keeps the package fully decoupled from the hot path — it never touches app/catalog or app/routing. (A lint-rule guard forbids routing/pipeline/keypool from importing it.)

Composition only. No HTTP, no chi/huma — the control plane binds these functions to routes. Pure-ish: I/O is the store reads; no mutation.

Index

Constants

This section is empty.

Variables

View Source 
var ErrNotFound = errors.New("catalogview: not found")

ErrNotFound is returned when {ref} resolves to no model/host. Handlers map it to 404.

Functions

This section is empty.

Types

type BindingView 

type BindingView struct {
	ID           string   `json:"id"`
	Adapter      string   `json:"adapter"`
	UpstreamName string   `json:"upstreamName,omitempty"`
	Enabled      bool     `json:"enabled"`
	Snapshots    []string `json:"snapshots,omitempty"`
}

type DeprecationView 

type DeprecationView struct {
	Status      string `json:"status"`
	SunsetDate  string `json:"sunsetDate,omitempty"`
	Replacement string `json:"replacement,omitempty"`
}

type HostKeyRef 

type HostKeyRef struct {
	ID                    string `json:"id"`
	Name                  string `json:"name"`
	Enabled               bool   `json:"enabled"`
	SharedWithPolicyCount int    `json:"sharedWithPolicyCount"` // # of OTHER policies referencing this key
}

type HostKeyView 

type HostKeyView struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Kind        string `json:"kind"` // "env" | "stored"
	DefaultTier string `json:"defaultTier,omitempty"`
	Enabled     bool   `json:"enabled"`
}

HostKeyView — one upstream credential targeting this host. Secret-free: only the value-mode discriminator and non-sensitive config.

type HostModelRow 

type HostModelRow struct {
	Model   ModelRef     `json:"model"`
	Binding BindingView  `json:"binding"`
	Pricing *PricingView `json:"pricing"`
}

HostModelRow — one model served by a host, with its binding + pricing.

type HostPolicyRow 

type HostPolicyRow struct {
	ID         string               `json:"id"`
	Name       string               `json:"name"`
	Enabled    bool                 `json:"enabled"`
	RateLimits []PolicyRateLimitRow `json:"rateLimits"`
}

HostPolicyRow — a host-tier policy this host owns, with its rate-limit rule sets (per-model RLBindings + the flat default).

type HostRef 

type HostRef struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	DisplayName string `json:"displayName,omitempty"`
	BaseURL     string `json:"baseURL,omitempty"`
	// Enabled + Icon are intrinsic host properties, carried on every HostRef
	// so "host off" flags and real logos render everywhere a host appears.
	Enabled bool      `json:"enabled"`
	Icon    *IconView `json:"icon,omitempty"`
}

type IconView 

type IconView struct {
	Path string `json:"path,omitempty"`
}

type Limit 

type Limit struct {
	Meter    string `json:"meter"`
	Amount   int64  `json:"amount"`
	Window   string `json:"window"`
	Strategy string `json:"strategy"`
}

type ModelHostRow 

type ModelHostRow struct {
	Host    HostRef      `json:"host"`
	Binding BindingView  `json:"binding"`
	Pricing *PricingView `json:"pricing"`
}

ModelHostRow — one host serving the model, with its binding + pricing.

type ModelPolicyRow 

type ModelPolicyRow struct {
	ID     string   `json:"id"`
	Name   string   `json:"name"`
	Owner  OwnerRef `json:"owner"`
	Limits []Limit  `json:"limits"`
}

ModelPolicyRow — flat: a policy that grants this model. Host-tier policies name their host via Owner; user policies grant across hosts (Owner.Kind "user"). Limits are the rules selected for THIS model (RLBinding/flat).

type ModelPriceRow 

type ModelPriceRow struct {
	Host     HostRef `json:"host"`
	ID       string  `json:"id"`
	Name     string  `json:"name"`
	Currency string  `json:"currency"`
	Rates    []Rate  `json:"rates"`
}

ModelPriceRow — flat: one host that prices this model (host inline).

type ModelRef 

type ModelRef struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	DisplayName string `json:"displayName,omitempty"`
	// Capabilities/context/deprecation are intrinsic model properties, so
	// they ride along on every ModelRef — the policy, host, and model tabs
	// all render the same capability icons + context window from one shape.
	Capabilities       []string         `json:"capabilities,omitempty"`
	ContextWindowTotal int              `json:"contextWindowTotal,omitempty"`
	ContextWindowInput int              `json:"contextWindowInput,omitempty"`
	Deprecation        *DeprecationView `json:"deprecation,omitempty"`
}

type OwnerRef 

type OwnerRef struct {
	Kind string `json:"kind"`         // "user" | "host" | "system" | …
	ID   string `json:"id,omitempty"` // for host-tier policies, the host id
	Name string `json:"name,omitempty"`
}

type PolicyBindingRow 

type PolicyBindingRow struct {
	Provider  ProviderRef `json:"provider"`
	Host      HostRef     `json:"host"`
	Model     ModelRef    `json:"model"`
	Binding   BindingView `json:"binding"`
	MatchedBy []string    `json:"matchedBy"`
	Limits    []Limit     `json:"limits"`
}

PolicyBindingRow — one concrete (provider, model, host) binding this policy grants, fully pre-joined. Mirrors ModelHostRow: the frontend renders rows and groups by host client-side, no catalog round-trip. MatchedBy carries the grant ref(s) that produced this row (raw Spec.Models entries, "*" for the implicit wildcard, or the model's canonical ref for an explicit ModelIDs grant) — the one fact the client can't recompute. Limits are resolved for THIS exact triple.

type PolicyHostRow 

type PolicyHostRow struct {
	Host        HostRef      `json:"host"`
	HostKeys    []HostKeyRef `json:"hostKeys"`
	Requirement string       `json:"requirement"` // "required" | "optional"
}

PolicyHostRow — a host this policy can reach, with the host-keys that reach it (empty for a host-tier policy's own host, which needs no key to qualify). Requirement is "required" when this host uniquely serves at least one model the policy grants (losing its key would drop that model), else "optional" — a sibling reachable host covers everything it does.

type PolicyModelExclusion 

type PolicyModelExclusion struct {
	Model  ModelRef `json:"model"`
	Reason string   `json:"reason"`
}

PolicyModelExclusion — a model this policy does NOT grant, with why. Surfaced by PolicyModelExclusions (the ?debug view) to make an empty grant diagnosable — e.g. a host-tier policy whose host has no bindings post-migration.

type PolicyRateLimitRow 

type PolicyRateLimitRow struct {
	ID      string   `json:"id"`
	Name    string   `json:"name"`
	Default bool     `json:"default"`
	Models  []string `json:"models,omitempty"`
	Limits  []Limit  `json:"limits"`
}

PolicyRateLimitRow — one rate-limit rule set the policy references. Default is the flat Spec.RateLimitID; the others are per-model RLBindings carrying their Models DSL.

type PolicyRateLimitsView 

type PolicyRateLimitsView struct {
	RateLimits  []PolicyRateLimitRow `json:"rateLimits"`
	Unthrottled []UnthrottledModel   `json:"unthrottled"`
	Overlaps    []RateLimitOverlap   `json:"overlaps"`
}

PolicyRateLimitsView is the rate-limits tab payload: the referenced rule sets plus the two derivations the server now owns — models that slip through uncapped, and bindings where RLBindings overlap.

type PolicyRef 

type PolicyRef struct {
	ID          string   `json:"id"`
	Name        string   `json:"name"`
	DisplayName string   `json:"displayName,omitempty"`
	Owner       OwnerRef `json:"owner"`
	Enabled     bool     `json:"enabled"`
}

PolicyRef identifies the policy a sub-resource response belongs to.

type PricingView 

type PricingView struct {
	ID       string `json:"id"`
	Name     string `json:"name"`
	Currency string `json:"currency"`
	Rates    []Rate `json:"rates"`
}

type ProviderRef 

type ProviderRef struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	DisplayName string `json:"displayName,omitempty"`
}

type Rate 

type Rate struct {
	Meter       string  `json:"meter"`
	Unit        string  `json:"unit"`
	Amount      float64 `json:"amount"`
	AboveTokens int     `json:"aboveTokens,omitempty"`
}

type RateLimitOverlap 

type RateLimitOverlap struct {
	Provider string   `json:"provider"`
	Model    string   `json:"model"`
	Host     string   `json:"host"`
	Winner   string   `json:"winner"`
	Losers   []string `json:"losers"`
}

RateLimitOverlap — a binding claimed by more than one RLBinding. Winner is the rate-limit that actually applies (first declared match); losers are the ones it shadowed on that binding. All ids match PolicyRateLimitRow.ID.

type Service 

type Service struct {
	Models     modelStore
	Hosts      hostStore
	Bindings   bindingStore
	Pricings   pricingStore
	Policies   policyStore
	RateLimits rateLimitStore
	Providers  providerStore
	HostKeys   hostKeyStore

	// Visible optionally scopes rows per owner: policy-rooted projections
	// 404 on a policy the caller may not see, and host-key / policy rows
	// inside other projections are dropped. Nil leaves every row visible
	// (the single-user default). kind is the singular resource kind
	// ("policy", "host-key").
	Visible func(kind string, owner meta.Owner) bool
}

Service composes the store reads into views. Construct once with the deployment's stores; methods are read-only.

func (*Service) HostKeyList 

func (s *Service) HostKeyList(ctx context.Context, ref string) (HostRef, []HostKeyView, error)

HostKeyList returns the upstream credentials this host owns (by id or slug).

func (*Service) HostModels 

func (s *Service) HostModels(ctx context.Context, ref string) (HostRef, []HostModelRow, error)

HostModels returns the models a host serves (by id or slug).

func (*Service) HostPolicies 

func (s *Service) HostPolicies(ctx context.Context, ref string) (HostRef, []HostPolicyRow, error)

HostPolicies returns the host-tier policies this host owns, with limits.

func (*Service) ModelHosts 

func (s *Service) ModelHosts(ctx context.Context, ref string) (ModelRef, []ModelHostRow, error)

ModelHosts returns the hosts serving the model (by id or slug), each with its binding and resolved pricing.

func (*Service) ModelPolicies 

func (s *Service) ModelPolicies(ctx context.Context, ref string) (ModelRef, []ModelPolicyRow, error)

ModelPolicies returns the policies that grant this model, flat. A policy grants the model when its id is in ModelIDs, it's an implicit wildcard, or a Models DSL ref matches on any host the model is bound to. Limits are the rules SelectRateLimitID picks for the model (resolved to numbers, so this is unaffected by a future limits-table removal).

func (*Service) ModelPricing 

func (s *Service) ModelPricing(ctx context.Context, ref string) (ModelRef, []ModelPriceRow, error)

ModelPricing returns the model's pricing per host, flat (host inline).

func (*Service) PolicyHosts 

func (s *Service) PolicyHosts(ctx context.Context, ref string) (PolicyRef, []PolicyHostRow, error)

PolicyHosts returns the hosts this policy can reach. Customer policies reach the hosts their host-keys authenticate to (keys folded in per host); a host-tier policy also reaches its own host.

func (*Service) PolicyModelExclusions 

func (s *Service) PolicyModelExclusions(ctx context.Context, ref string) (PolicyRef, []PolicyModelExclusion, error)

PolicyModelExclusions returns the models this policy does NOT grant, each with the reason — the diagnostic complement to PolicyModels. Use it to explain an empty grant list (missing bindings, deprecation gate, non-matching DSL).

func (*Service) PolicyModels 

func (s *Service) PolicyModels(ctx context.Context, ref string) (PolicyRef, []PolicyBindingRow, error)

PolicyModels returns one row per concrete (model, host) binding this policy grants. Resolution mirrors routing: an explicit ModelIDs grant is host- and coverage-agnostic (emits on every binding of the model); wildcard and Models DSL grants emit only on hosts the policy actually reaches (host-tier: its own host; customer: hosts its host-keys cover). Limits are resolved per triple.

func (*Service) PolicyRateLimits 

func (s *Service) PolicyRateLimits(ctx context.Context, ref string) (PolicyRef, PolicyRateLimitsView, error)

PolicyRateLimits returns the rate-limit rule sets the policy references — each per-model RLBinding in declared order, then the flat default last — plus the unthrottled-models and overlapping-binding derivations.

type UnthrottledModel 

type UnthrottledModel struct {
	Model ModelRef `json:"model"`
}

UnthrottledModel — a model the policy grants on which no rate-limit applies (every granted binding of it resolves to an empty limit set).

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.