diagnostic

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Nov 13, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package diagnostic contains shared rendering and bounded cursor mechanics for owner-defined MCP diagnostics. It has no HTTP transport or dispatcher. Owners retain their typed records and decide which data is safe to expose.

Example: diagnostic.Millis(time.Second) yields 1000 for duration_ms.

Index

Constants

View Source
const (
	// StatusOK describes a successful observation, not a transport status.
	// Example: result.Status = diagnostic.StatusOK
	StatusOK = "ok"
	// StatusFailing describes fresh failed health checks.
	// Example: if report.Status == diagnostic.StatusFailing { fmt.Println("unhealthy") }
	StatusFailing = "failing"
	// StatusPending means a background check has not completed yet.
	// Example: if report.Status == diagnostic.StatusPending { fmt.Println("waiting") }
	StatusPending = "pending"
	// StatusError marks an errored trace or span.
	// Example: if span.Status == diagnostic.StatusError { fmt.Println("failed") }
	StatusError = "error"
	// StatusUnset means the span never received an explicit status.
	// Example: if span.Status == diagnostic.StatusUnset { fmt.Println("no status") }
	StatusUnset = "unset"
)

Variables

This section is empty.

Functions

func Age

func Age(observedAt, occurredAt time.Time) string

Age describes a timestamp relative to observedAt, with second precision or the largest whole unit. Zero timestamps return empty text for absent values. Example: text := diagnostic.Age(time.Unix(60, 0), time.Unix(0, 0))

func Bytes

func Bytes(bytes uint64) string

Bytes renders byte counts using binary prefixes and one decimal place. Example: text := diagnostic.Bytes(1024) // "1.0KiB"

func DurationSchema

func DurationSchema(description string) validate.TextSchema[validate.Duration]

DurationSchema describes a nonnegative duration filter. Zero means that the owner imposes no age or duration restriction. Example: schema := diagnostic.DurationSchema("Maximum age, such as 30s")

func DurationText

func DurationText(duration time.Duration) validate.Duration

DurationText rounds durations for display without changing the machine value. Values below one second round to microseconds, others to milliseconds. Example: text := diagnostic.DurationText(time.Second)

func LimitSchema

func LimitSchema(fallback int) validate.IntSchema[int]

LimitSchema bounds diagnostic pages to 1000 items and supplies fallback when the caller omits the property or supplies zero, matching typed defaults. Example: schema := diagnostic.LimitSchema(100)

func Millis

func Millis(duration time.Duration) float64

Millis returns fractional milliseconds for machine-readable duration fields. Example: milliseconds := diagnostic.Millis(250 * time.Millisecond)

func NewInstance

func NewInstance() string

NewInstance creates a nonsecret store-generation identifier. Resetting a store assigns a new identifier so empty resets remain observable. Example: id := diagnostic.NewInstance()

func WaitSchema

func WaitSchema() validate.TextSchema[validate.Duration]

WaitSchema describes a polling duration with a hard 25-second bound. The owner may omit this property for an immediate diagnostic snapshot. Example: schema := diagnostic.WaitSchema()

Types

type CursorRequest

type CursorRequest struct {
	// Key binds a cursor to exactly one tool and filter combination.
	// Example: request.Key = "app.events|billing.*"
	Key string
	// Cursor is empty for history, "tail" for an immediate empty anchor.
	// Example: request.Cursor = "tail"
	Cursor string
	// Wait bounds an idle continuation call; zero returns immediately.
	// Example: request.Wait = time.Second
	Wait time.Duration
	// Limit bounds emitted items and must be between 1 and 1000.
	// Example: request.Limit = 100
	Limit int
}

CursorRequest contains one bounded call's controls. Key includes the tool identity and normalized filters, excluding cursor, wait, and page size. Example: request := diagnostic.CursorRequest{Key: "app.events|*", Limit: 100}

type Feed

type Feed[T, Out any] struct {
	// Snapshot copies a consistent ring state and notification.
	// Example: state := feed.Snapshot()
	Snapshot func() Snapshot[T]
	// Match decides whether a retained record belongs in this query.
	// Example: accepted := feed.Match(record)
	Match func(T) bool
	// Render converts an accepted record to the owner diagnostic DTO.
	// Example: item := feed.Render(record)
	Render func(T) Out
}

Feed binds a store snapshot to owner-specific filtering and rendering. All functions are synchronous; Snapshot must take one atomic observation. Example: feed := diagnostic.Feed[string,string]{Snapshot: snapshot, Match: match, Render: render}

type List

type List[T any] struct {
	// Items holds matching records in the owner's documented order.
	// Example: result.Items = append(result.Items, "ready")
	Items []T `json:"items"`
	// Truncated indicates that matching history exceeded the requested limit.
	// Example: if result.Truncated { fmt.Println("more history exists") }
	Truncated bool `json:"truncated"`
}

List is an object-shaped diagnostic result. Items is non-nil at owner boundaries; Truncated describes an intentionally bounded history snapshot.

Example: result := diagnostic.List[string]{Items: []string{"ready"}}

type Page

type Page[T any] struct {
	// Items contains records oldest first, never null.
	// Example: for _, item := range page.Items { fmt.Println(item) }
	Items []T `json:"items"`
	// Truncated reports history omitted from a cursor-less snapshot.
	// Example: if page.Truncated { fmt.Println("history bounded") }
	Truncated bool `json:"truncated"`
	// Cursor is an opaque continuation token, including when Items is empty.
	// Example: arguments.Cursor = page.Cursor
	Cursor string `json:"cursor"`
	// Dropped counts overwritten records, including uninspectable nonmatches.
	// Example: if page.Dropped > 0 { fmt.Println("records lost") }
	Dropped uint64 `json:"dropped"`
	// HasMore means retained matching records remain after this page.
	// Example: if page.HasMore { /* call again without waiting */ }
	HasMore bool `json:"has_more"`
	// InstanceChanged marks store replacement or reset; Cursor is a fresh tail.
	// Example: if page.InstanceChanged { fmt.Println("capture restarted") }
	InstanceChanged bool `json:"instance_changed"`
}

Page contains a bounded cursor result. History snapshots may be truncated; continuation pages instead report HasMore and never skip matching records. Example: var page diagnostic.Page[string]; _ = page.Cursor

func Poll

func Poll[T, Out any](ctx context.Context, request CursorRequest, feed Feed[T, Out]) (Page[Out], error)

Poll returns a history snapshot, immediate tail anchor, or bounded continuation. One fixed timer spans every notification, including nonmatches. Cancellation returns ctx.Err without manufacturing a successful response. Malformed, foreign-filter, and future cursors produce a safe ToolFailure. Example: page, err := diagnostic.Poll(ctx, request, feed)

type Snapshot

type Snapshot[T any] struct {
	// Items holds the newest len(Items) records, in ascending sequence order.
	// Example: snapshot.Items = []string{"record"}
	Items []T
	// Total is the sequence number of the newest record, even on an empty ring.
	// Example: snapshot.Total = 1
	Total uint64
	// Instance changes on reset and is unique per store, not per tool factory.
	// Example: snapshot.Instance = diagnostic.NewInstance()
	Instance string
	// Changed closes when records arrive or the store resets.
	// Example: select { case <-snapshot.Changed: case <-ctx.Done(): }
	Changed <-chan struct{}
}

Snapshot atomically pairs retained contiguous records with the high-water mark and notification channel. Owners copy records while holding their lock. Example: snapshot := diagnostic.Snapshot[string]{Items: []string{}, Instance: id}

Jump to

Keyboard shortcuts

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