openapipreview

package

v1.0.0-rc.1 Latest Latest Go to latest Published: Sep 9, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/gridctl/gridctl

Links

Open Source Insights

Documentation ¶

Overview ¶

Package openapipreview parses an OpenAPI spec on demand so the create-server wizard can show which operations exist before anything is deployed.

It is deliberately a sibling of internal/probe rather than part of it. The probe performs an MCP handshake and returns []mcp.Tool, which discards the method, path, and tags a spec picker needs to filter on. The two share infrastructure patterns (TTL cache, stable error codes) but not a code path.

Index ¶

Constants
func Key(req Request) string
type Cache
- func NewCache(ttl time.Duration) *Cache
type Entry
type Error
- func (e *Error) Error() string
type Previewer
- func New(cache *Cache, logger *slog.Logger) *Previewer
- func (p *Previewer) Preview(ctx context.Context, req Request) (*Result, *Error)
type Request
type Result

Constants ¶

View Source

const (
	CodeInvalidRequest = "invalid_request"
	CodeNeedsAuth      = "needs_auth"
	CodeFetchFailed    = "fetch_failed"
	CodeParseFailed    = "parse_failed"
	CodeRateLimited    = "rate_limited"
	CodeInternal       = "internal"
)

Stable error codes. The web UI keys its copy off these, so treat them as a wire contract: add new ones rather than repurposing existing ones.

View Source

const DefaultTTL = 5 * time.Minute

DefaultTTL is how long a successful preview is cached.

Variables ¶

This section is empty.

Functions ¶

func Key ¶

func Key(req Request) string

Key produces a stable hash of everything that changes what a preview returns. Fields are hashed through a fixed-order struct so the bytes are stable across semantically identical requests.

Types ¶

type Cache ¶

type Cache struct {
	// contains filtered or unexported fields
}

Cache is a concurrency-safe TTL cache for preview results. The zero value is not usable — call NewCache.

func NewCache ¶

func NewCache(ttl time.Duration) *Cache

NewCache constructs a preview cache with the given TTL. Zero or negative TTLs fall back to DefaultTTL so callers cannot accidentally disable caching.

func (*Cache) Get ¶

func (c *Cache) Get(key string) (Entry, bool)

Get returns the entry for key if present and unexpired, evicting lazily.

func (*Cache) Len ¶

func (c *Cache) Len() int

Len reports the number of entries, including expired ones not yet evicted. Intended for tests.

func (*Cache) Put ¶

func (c *Cache) Put(key string, entry Entry)

Put stores a successful preview. Failure paths must not populate the cache.

type Entry ¶

type Entry struct {
	Title      string
	Version    string
	Operations []mcp.OperationSummary
	LoadedAt   time.Time
}

Entry is a cached preview result.

type Error ¶

type Error struct {
	Code    string
	Message string
	Hint    string
}

Error is a structured preview failure carrying operator-facing guidance.

func (*Error) Error ¶

func (e *Error) Error() string

type Previewer ¶

type Previewer struct {
	// contains filtered or unexported fields
}

Previewer parses specs and caches successful results.

func New ¶

func New(cache *Cache, logger *slog.Logger) *Previewer

New constructs a Previewer. A nil cache disables caching; a nil logger falls back to the default.

func (*Previewer) Preview ¶

func (p *Previewer) Preview(ctx context.Context, req Request) (*Result, *Error)

Preview loads a spec and returns its operations, including the ones that cannot become tools. Only successes are cached; failures always re-run so a transient outage does not pin an error for the cache lifetime.

type Request ¶

type Request struct {
	Spec               string
	CertFile           string
	KeyFile            string
	CAFile             string
	InsecureSkipVerify bool
}

Request identifies the spec to parse.

There is deliberately no auth block: spec fetching is unauthenticated on the deployed path too, because API credentials authenticate calls to the API, not retrieval of its description. TLS material is accepted because a spec served from an mTLS-protected host cannot be fetched without it.

type Result ¶

type Result struct {
	Title      string
	Version    string
	Operations []mcp.OperationSummary
	Cached     bool
	LoadedAt   time.Time
}

Result is a parsed spec's operation list plus the identity of the document.

Source Files ¶

View all Source files

preview.go

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL