apicatalog

package
v1.0.59 Latest Latest
Warning

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

 Go to latest Published: Jun 26, 2026 License: MIT Imports: 3 Imported by: 0

Documentation

Overview

Package apicatalog is the single navigation Module over the API metadata. 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; registry is the source Adapter (EmbeddedCatalog/RuntimeCatalog), so apicatalog never imports registry.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ParsePath 

func ParsePath(args []string) []string

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 navigation view over services with a name index. It owns its ordering — New sorts by name — so WalkMethods/Resolve/Complete are deterministic regardless of how the source adapter ordered its input.

func New 

func New(source Source, services []meta.Service) Catalog

New builds a Catalog over the given services, owning its navigation order: the slice is copied and sorted by name so callers may pass any order and the ordering contract is not delegated to the adapter. The copy is shallow — meta.Service values share their Resources maps, which are treated as read-only.

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) 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) Resolve 

func (c Catalog) Resolve(parts []string) (Target, error)

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) Service 

func (c Catalog) Service(name string) (meta.Service, bool)

Service looks up one service by name.

func (Catalog) Services 

func (c Catalog) Services() []meta.Service

Services returns the services in name order. Treat the result as read-only: it is the Catalog's own ordered slice and its element Resources maps are shared.

func (Catalog) Source 

func (c Catalog) Source() Source

Source reports embedded vs runtime.

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 MethodFilter 

type MethodFilter func(meta.Method) bool

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 

func (r MethodRef) CommandPath() []string

CommandPath is the CLI argv segments, e.g. ["im", "chat.members", "create"].

func (MethodRef) MethodName 

func (r MethodRef) MethodName() string

MethodName returns the method's own name.

func (MethodRef) ResourceName 

func (r MethodRef) ResourceName() string

ResourceName is the dotted resource path, e.g. "chat.members".

func (MethodRef) SchemaPath 

func (r MethodRef) SchemaPath() string

SchemaPath is the dotted "service.resource.method" identifier, e.g. "im.chat.members.create".

func (MethodRef) ServiceName 

func (r MethodRef) ServiceName() string

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 

type ResourceRef struct {
	Service  meta.Service
	Resource meta.Resource
	Path     []string
}

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 whether a catalog includes the remote overlay. It is carried so callers (and tests) can assert determinism instead of guessing. 

const (
	SourceEmbedded Source = "embedded" // compiled-in metadata only; deterministic
	SourceRuntime  Source = "runtime"  // embedded + remote overlay
)

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

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.