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
- func Age(observedAt, occurredAt time.Time) string
- func Bytes(bytes uint64) string
- func DurationSchema(description string) validate.TextSchema[validate.Duration]
- func DurationText(duration time.Duration) validate.Duration
- func LimitSchema(fallback int) validate.IntSchema[int]
- func Millis(duration time.Duration) float64
- func NewInstance() string
- func WaitSchema() validate.TextSchema[validate.Duration]
- type CursorRequest
- type Feed
- type List
- type Page
- type Snapshot
Constants ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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}