Documentation
¶
Index ¶
- Constants
- Variables
- type GatewayAdapter
- type PinFile
- type PinRecord
- type PinStore
- func (ps *PinStore) Approve(serverName string, tools []mcp.Tool) error
- func (ps *PinStore) GetAll() map[string]*ServerPins
- func (ps *PinStore) GetServer(serverName string) (*ServerPins, bool)
- func (ps *PinStore) Load() error
- func (ps *PinStore) Reset(serverName string) error
- func (ps *PinStore) Verify(serverName string, tools []mcp.Tool) (*VerifyResult, error)
- func (ps *PinStore) VerifyOrPin(serverName string, tools []mcp.Tool) (*VerifyResult, error)
- type ServerPins
- type ToolDiff
- type VerifyResult
Constants ¶
const ( StatusPinned = "pinned" StatusDrift = "drift" StatusApprovedPendingRedeploy = "approved_pending_redeploy" )
Status values for ServerPins.
const ( VerifyStatusPinned = "pinned" // first pin, just stored VerifyStatusVerified = "verified" // hashes match VerifyStatusDrift = "drift" // tool hashes changed VerifyStatusNewTools = "new_tools" // server added tools (no drift, auto-pinned) VerifyStatusRemovedTools = "removed_tools" // server removed tools (warning only) )
Verify status values returned in VerifyResult.
Variables ¶
var ( ErrCorrupt = errors.New("corrupt pin file") ErrNewerVersion = errors.New("pin file written by a newer gridctl") )
Sentinel errors reported by Load. A caller that prefers availability over strictness (the daemon) may match ErrCorrupt and continue with the empty store Load leaves behind; ErrNewerVersion must never be papered over, or this binary would re-pin from scratch and overwrite the newer file.
Functions ¶
This section is empty.
Types ¶
type GatewayAdapter ¶
type GatewayAdapter struct {
// contains filtered or unexported fields
}
GatewayAdapter wraps PinStore to implement mcp.SchemaVerifier. It bridges the pins package to the gateway without creating an import cycle: pkg/pins already imports pkg/mcp for the Tool type, so pkg/mcp cannot import pkg/pins in return. The gateway holds a mcp.SchemaVerifier interface, and callers wire it with a GatewayAdapter at startup.
func NewGatewayAdapter ¶
func NewGatewayAdapter(ps *PinStore) *GatewayAdapter
NewGatewayAdapter creates a GatewayAdapter backed by the given PinStore.
func (*GatewayAdapter) ResetServerPins ¶
func (a *GatewayAdapter) ResetServerPins(serverName string) error
ResetServerPins implements mcp.PinResetter. It deletes the pin record for serverName so the next VerifyOrPin re-pins from scratch.
func (*GatewayAdapter) VerifyOrPin ¶
func (a *GatewayAdapter) VerifyOrPin(serverName string, tools []mcp.Tool) ([]mcp.SchemaDrift, error)
VerifyOrPin implements mcp.SchemaVerifier. It delegates to PinStore.VerifyOrPin and converts the result into the mcp.SchemaDrift slice that the gateway consumes.
type PinFile ¶
type PinFile struct {
Version string `json:"version"`
Stack string `json:"stack"`
CreatedAt time.Time `json:"created_at"`
Servers map[string]*ServerPins `json:"servers"`
}
PinFile is the top-level JSON structure stored at ~/.gridctl/pins/{stackName}.json.
type PinRecord ¶
type PinRecord struct {
Hash string `json:"hash"`
Name string `json:"name"`
Description string `json:"description,omitempty"`
PinnedAt time.Time `json:"pinned_at"`
}
PinRecord holds the hash and metadata for a single tool definition. Description is stored to enable human-readable diff output on drift.
type PinStore ¶
type PinStore struct {
// contains filtered or unexported fields
}
PinStore manages TOFU schema pins for a deployed stack. It is safe for concurrent use: in-memory access is guarded by a RWMutex, and disk writes are serialized via state.WithLock.
func New ¶
New creates a PinStore for the given stack name. The pin file lives at ~/.gridctl/pins/{stackName}.json. Call Load() before performing verification or pinning operations.
func NewWithPath ¶
NewWithPath creates a PinStore that stores pins in dir/{stackName}.json. Intended for testing where the real state directory should not be used.
func (*PinStore) Approve ¶
Approve re-pins the current tool definitions for a server, clearing drift.
func (*PinStore) GetAll ¶
func (ps *PinStore) GetAll() map[string]*ServerPins
GetAll returns a snapshot of all server pin records.
func (*PinStore) GetServer ¶
func (ps *PinStore) GetServer(serverName string) (*ServerPins, bool)
GetServer returns the pin record for a single server.
func (*PinStore) Load ¶
Load reads the pin file from disk into memory. If the file does not exist, the store starts empty (ready for first pin). A file that cannot be parsed returns an error wrapping ErrCorrupt, and a file written by a newer gridctl returns one wrapping ErrNewerVersion; in both cases the in-memory store is reset to empty so a caller that chooses to continue anyway has a usable store.
func (*PinStore) Reset ¶
Reset deletes the pin record for a server. The next VerifyOrPin call will re-pin.
func (*PinStore) Verify ¶
Verify checks tools against stored pins without pinning new tools. Unlike VerifyOrPin, new tools are not auto-pinned.
func (*PinStore) VerifyOrPin ¶
VerifyOrPin is the primary entry point called on RefreshTools. On first use it pins the tools; on subsequent calls it verifies against pins. New tools not in pins are auto-pinned; modified tools trigger VerifyStatusDrift.
type ServerPins ¶
type ServerPins struct {
ServerHash string `json:"server_hash"`
PinnedAt time.Time `json:"pinned_at"`
LastVerifiedAt time.Time `json:"last_verified_at"`
ToolCount int `json:"tool_count"`
Status string `json:"status"`
Tools map[string]*PinRecord `json:"tools"`
}
ServerPins holds the pin state for a single MCP server.
type ToolDiff ¶
type ToolDiff struct {
Name string
OldHash string
NewHash string
OldDescription string
NewDescription string
}
ToolDiff describes a change in a single tool's definition.
type VerifyResult ¶
type VerifyResult struct {
ServerName string
Status string
ModifiedTools []ToolDiff
NewTools []string
RemovedTools []string
}
VerifyResult contains the result of a VerifyOrPin or Verify call.
func (*VerifyResult) HasDrift ¶
func (r *VerifyResult) HasDrift() bool
HasDrift returns true if any pinned tools have changed hashes.
Source Files