Documentation
¶
Overview ¶
Package apicatalog is the single navigation module over API catalog data. It owns every "which services/resources/methods exist and how does a path resolve" question that was previously duplicated across cmd/schema, cmd/service, internal/schema and internal/registry. It depends only on internal/meta; apicatalog never imports the snapshot loader.
Index ¶
- Variables
- func ParsePath(args []string) []string
- type Catalog
- func (c Catalog) Complete(args []string, toComplete string, filter MethodFilter) (completions []string, noSpace bool)
- func (c Catalog) Err() error
- func (c Catalog) MethodRefs(target Target, filter MethodFilter) []MethodRef
- func (c Catalog) Names() []string
- func (c Catalog) Preload(names ...string) error
- func (c Catalog) Resolve(parts []string) (Target, error)
- func (c Catalog) Service(name string) (meta.Service, bool)
- func (c Catalog) Services() []meta.Service
- func (c Catalog) Source() Source
- func (c Catalog) WalkMethods(filter MethodFilter) []MethodRef
- type Loader
- type MethodFilter
- type MethodRef
- type ResolveError
- type ResolveErrorKind
- type ResourceRef
- type Source
- type Target
- type TargetKind
Constants ¶
This section is empty.
Variables ¶
var ErrServiceNotFound = errors.New("apicatalog: service not found")
ErrServiceNotFound is returned by a Loader whose Names listed a service that it cannot provide after all (for example a projection that removed every reachable method). The Catalog treats it as "absent", not as a failure.
Functions ¶
func ParsePath ¶
ParsePath normalizes positional command arguments into the path segments Resolve consumes. It accepts two equivalent forms:
im.messages.reply -> single arg, split on "." im messages reply -> multiple args, used as-is
"im chat.members bots" as a single quoted arg is NOT supported; quote arguments individually if your shell needs it. A resource keeps its internal dots when passed as one segment (e.g. "chat.members"); findResource's longest-prefix descent resolves both the split and the one-segment forms to the same target. Returns nil for zero args (bare invocation -> TargetAll).
Types ¶
type Catalog ¶
type Catalog struct {
// contains filtered or unexported fields
}
Catalog is a cheap-to-copy navigation handle over services. Copies share one lazily populated state, so a service body is parsed at most once per Catalog no matter how many holders navigate it. The zero Catalog is empty.
Navigation is lenient by design: Service reports a failed shard as absent, and Services, WalkMethods, Resolve, and completion skip it, so help and completion keep working for the rest of the catalog. A caller whose result must not silently shrink when a shard is corrupt — anything that persists, authorizes, or enumerates "everything" — calls Preload for the names it is about to consult (or checks Err after enumerating) and returns that typed error instead of continuing.
func Filter ¶ added in v1.0.95
Filter derives a Catalog whose services are the result of applying keep to each service of c on first use. keep returns the (possibly reduced) service and false to drop it. The derived Catalog shares no cache with c beyond what c itself has already parsed.
func New ¶
New builds an eager Catalog over the given services. The slice is copied and sorted by name so callers may pass any order. The copy is shallow — meta.Service values share their Resources maps, which are treated as read-only.
func NewLazy ¶ added in v1.0.95
NewLazy builds a Catalog that parses services on first use through loader.
func (Catalog) Complete ¶
func (c Catalog) Complete(args []string, toComplete string, filter MethodFilter) (completions []string, noSpace bool)
Complete returns shell-completion candidates for the schema path argument, supporting both the legacy single dotted arg ("im.reac") and the space-separated form ("im reactions"). noSpace mirrors cobra's ShellCompDirectiveNoSpace (so "service." / "service.resource." stay open for the next segment). Filtering uses the caller's MethodFilter so strict-mode unavailable methods are hidden.
func (Catalog) Err ¶ added in v1.0.95
Err returns the first source failure observed while loading services (never ErrServiceNotFound). Enumeration paths that must not hide a corrupt source check it after Services or WalkMethods.
func (Catalog) MethodRefs ¶
func (c Catalog) MethodRefs(target Target, filter MethodFilter) []MethodRef
MethodRefs returns the method refs selected by a resolved Target, filtered: TargetAll -> every method, TargetService / TargetResource -> that subtree, TargetMethod -> the single method if it passes the filter (else empty). It unifies WalkMethods/ServiceMethods/ResourceMethods so the command layer maps a Target to refs in one call instead of re-deciding the walker per Kind.
func (Catalog) Names ¶ added in v1.0.95
Names returns the sorted names the underlying loader can provide, without parsing any service body. A projected service may still be absent from Services; callers that need the exact resolvable set use Services.
func (Catalog) Preload ¶ added in v1.0.95
Preload parses the named services now, distinct shards in parallel, and returns the first failure. Build paths use it so a corrupt service surfaces as a typed error before any command is dispatched; afterwards Service and Services for those names are pure cache hits.
func (Catalog) Resolve ¶
Resolve maps a path (already split into segments) to a Target. An empty path is TargetAll. Failures return a *ResolveError carrying the available candidates so the command layer can render a hint.
func (Catalog) Services ¶
Services returns every resolvable service in name order, loading any that have not been parsed yet. Treat the result as read-only: it is the Catalog's own ordered slice and its element Resources maps are shared. Services whose Load failed are omitted; the failure is retained for Err.
func (Catalog) WalkMethods ¶
func (c Catalog) WalkMethods(filter MethodFilter) []MethodRef
WalkMethods returns one MethodRef per method across all services (optionally filtered), recursing nested resources, in a deterministic order: services by name, resources by name, methods by name.
type Loader ¶ added in v1.0.95
Loader is the per-service data source behind a lazy Catalog. Names must be cheap and must not parse service bodies; Load parses exactly one service and owns its integrity: a successful Load returns a service whose Name is the requested name. Any error other than ErrServiceNotFound is a source failure that the Catalog records (see Catalog.Err) and surfaces through Preload.
type MethodFilter ¶
MethodFilter optionally drops methods (e.g. by identity in strict mode). A nil filter includes everything.
type MethodRef ¶
type MethodRef struct {
Service meta.Service
Resource meta.Resource
ResourcePath []string
Method meta.Method
}
MethodRef identifies one method, carrying the full navigation context so the command path and schema path can be derived without re-walking the catalog.
func ResourceMethods ¶
func ResourceMethods(r ResourceRef, filter MethodFilter) []MethodRef
ResourceMethods returns the method refs under one resource (filtered), using the resource's resolved path as the base and recursing nested resources.
func ServiceMethods ¶
func ServiceMethods(svc meta.Service, filter MethodFilter) []MethodRef
ServiceMethods returns the method refs of one service (filtered), recursing nested resources, in deterministic resource/method name order.
func (MethodRef) CommandPath ¶
CommandPath is the CLI argv segments, e.g. ["im", "chat.members", "create"].
func (MethodRef) MethodName ¶
MethodName returns the method's own name.
func (MethodRef) ResourceName ¶
ResourceName is the dotted resource path, e.g. "chat.members".
func (MethodRef) SchemaPath ¶
SchemaPath is the dotted "service.resource.method" identifier, e.g. "im.chat.members.create".
func (MethodRef) ServiceName ¶
ServiceName returns the owning service name.
type ResolveError ¶
type ResolveError struct {
Kind ResolveErrorKind
Subject string
Candidates []string
Method string
Trailing string
}
ResolveError is returned by Catalog.Resolve. Subject is the dotted thing that failed to resolve; Candidates lists the available names at that level (nil for ErrPath, which instead carries the matched Method and the unresolved Trailing).
func (*ResolveError) Error ¶
func (e *ResolveError) Error() string
type ResolveErrorKind ¶
type ResolveErrorKind string
ResolveErrorKind classifies a Resolve failure so the command layer can render the right hint without re-deriving what was being looked up.
const ( ErrService ResolveErrorKind = "service" ErrResource ResolveErrorKind = "resource" ErrMethod ResolveErrorKind = "method" ErrPath ResolveErrorKind = "path" // method exists but trailing segments don't resolve )
type ResourceRef ¶
ResourceRef identifies one resource within a service. Path holds the resource path segments (one element for the common flat dotted resource like "chat.members"; multiple for genuinely nested resources).
func (ResourceRef) SchemaPath ¶
func (r ResourceRef) SchemaPath() string
SchemaPath is the dotted "service.resource" identifier.
type Source ¶
type Source string
Source records the immutable origin of a Catalog.
const (
SourceEmbedded Source = "embedded"
)
type Target ¶
type Target struct {
Kind TargetKind
Service meta.Service
Resource *ResourceRef
Method *MethodRef
}
Target is the result of Catalog.Resolve. Resource and Method are populated only for TargetResource and TargetMethod respectively.
type TargetKind ¶
type TargetKind string
TargetKind classifies what a schema/command path resolves to.
const ( TargetAll TargetKind = "all" // empty path: every method TargetService TargetKind = "service" // <service> TargetResource TargetKind = "resource" // <service> <resource...> TargetMethod TargetKind = "method" // <service> <resource...> <method> )
Source Files