Documentation
¶
Overview ¶
Package sets holds named lists of skills and their immutable resolutions.
Index ¶
- Constants
- Variables
- func CheckKeySet(ctx context.Context, set *Set) error
- func RegisterRoutes(api huma.API, router chi.Router, store *Store, storage platform.Storage)
- func ResolutionID(entries []ResolvedEntry) string
- func WriteBundle(ctx context.Context, w io.Writer, storage platform.Storage, res *Resolution, ...) error
- type BundleManifest
- type BundleManifestSkill
- type ChangeNotifier
- type ExcludedEntry
- type GoneError
- type Querier
- type Resolution
- type ResolvedEntry
- type Set
- type SetCaller
- type SetDetail
- type SetEntry
- type Store
- func (s *Store) ArchivePath(ctx context.Context, name string, version int) (string, error)
- func (s *Store) Callers(ctx context.Context, set *Set) ([]SetCaller, error)
- func (s *Store) CheckAvailable(ctx context.Context, res *Resolution) (map[string]string, error)
- func (s *Store) Create(ctx context.Context, name, description string, entries []SetEntry, ...) (*Set, error)
- func (s *Store) Delete(ctx context.Context, name, actor string) (bool, error)
- func (s *Store) Get(ctx context.Context, name string) (*Set, error)
- func (s *Store) GetByID(ctx context.Context, id string) (*Set, error)
- func (s *Store) GetResolution(ctx context.Context, set *Set, id string) (*Resolution, error)
- func (s *Store) List(ctx context.Context) ([]Set, error)
- func (s *Store) Recheck(ctx context.Context, tx pgx.Tx, setID string) (*Set, *Resolution, bool, error)
- func (s *Store) RecordCaller(ctx context.Context, set *Set, userID, name, resolutionID string) error
- func (s *Store) SaveResolution(ctx context.Context, set *Set, res *Resolution) error
- func (s *Store) SetNotifier(n ChangeNotifier)
- func (s *Store) SkillVersionExists(ctx context.Context, name string, version int) (bool, error)
- func (s *Store) Update(ctx context.Context, name, description string, entries []SetEntry, ...) (*Set, error)
Constants ¶
const ( ReasonSkillNotFound = "skill_not_found" ReasonNoReleasedVersion = "no_released_version" ReasonVersionNotFound = "version_not_found" ReasonHeld = "held" ReasonRejected = "rejected" )
The reasons an entry is excluded.
const BundleRoot = ".agents/skills"
BundleRoot is where a bundle places skills, for any agent to read.
Variables ¶
var ErrNameTaken = errors.New("set name already exists")
ErrNameTaken reports a duplicate set name.
Functions ¶
func CheckKeySet ¶
CheckKeySet applies a set-limited key's limit. A deleted set gives 403, so the key never becomes unrestricted and never learns which sets exist.
func RegisterRoutes ¶
RegisterRoutes wires the set endpoints.
func ResolutionID ¶
func ResolutionID(entries []ResolvedEntry) string
ResolutionID hashes the sorted name, version and digest list.
Types ¶
type BundleManifest ¶
type BundleManifest struct {
Set string `json:"set"`
ResolutionID string `json:"resolution_id"`
Complete bool `json:"complete"`
Skills []BundleManifestSkill `json:"skills"`
}
BundleManifest is written at BundleRoot/manifest.json.
type BundleManifestSkill ¶
type BundleManifestSkill struct {
Name string `json:"name"`
Version int `json:"version"`
SHA256 string `json:"sha256"`
Archive string `json:"archive"`
}
BundleManifestSkill names one skill in a bundle. SHA256 is the digest of the skill's archive, which the bundle carries at Archive so a consumer can check it: an unpacked tree cannot reproduce the digest of an uploaded archive.
type ChangeNotifier ¶
ChangeNotifier hears of a set edit inside its transaction.
type ExcludedEntry ¶
type ExcludedEntry struct {
Name string `json:"name"`
Requested string `json:"requested"`
Reason string `json:"reason"`
}
ExcludedEntry is a set entry that a resolve could not serve.
type GoneError ¶
type GoneError struct{ Skill string }
GoneError names the skill a stored resolution can no longer serve.
type Querier ¶
type Querier interface {
Exec(ctx context.Context, sql string, args ...any) (pgconn.CommandTag, error)
QueryRow(ctx context.Context, sql string, args ...any) pgx.Row
Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)
}
Querier runs against a pool or a transaction.
type Resolution ¶
type Resolution struct {
ID string `json:"id"`
Set string `json:"set"`
Complete bool `json:"complete"`
Entries []ResolvedEntry `json:"entries"`
Excluded []ExcludedEntry `json:"excluded,omitempty"`
}
Resolution is the immutable result of resolving a set.
func Resolve ¶
Resolve computes the set's current resolution through q. It stores nothing, so a caller can compare it inside a transaction.
func ResolveAndRecord ¶
ResolveAndRecord resolves a set, stores the resolution and notes the caller. Only an API key counts as a caller: a person browsing the UI consumes nothing.
type ResolvedEntry ¶
type ResolvedEntry struct {
Name string `json:"name"`
Version int `json:"version"`
SHA256 string `json:"sha256"`
ScanVerdict string `json:"scan_verdict"`
ApprovalState string `json:"approval_state"`
}
ResolvedEntry is one exact version in a resolution.
type Set ¶
type Set struct {
ID string `json:"id"`
Name string `json:"name"`
Description string `json:"description"`
Entries []SetEntry `json:"entries"`
CreatedBy string `json:"created_by"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
Set is a named list of skills.
type SetCaller ¶
type SetCaller struct {
Name string `json:"name"`
ResolutionID string `json:"resolution_id"`
LastSeenAt time.Time `json:"last_seen_at"`
}
SetCaller is the last use of a set by one identity.
type SetEntry ¶
type SetEntry struct {
Name string `json:"name"`
Version int `json:"version,omitempty" doc:"An exact version. Omit it for latest."`
}
SetEntry is one skill in a set. Version 0 means latest.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store persists sets.
func (*Store) ArchivePath ¶
ArchivePath returns where a resolved version's archive lives, or "" when its skill or version has gone.
func (*Store) CheckAvailable ¶
CheckAvailable returns the archive path of each entry, or a GoneError before any byte of the response is written.
func (*Store) Create ¶
func (s *Store) Create(ctx context.Context, name, description string, entries []SetEntry, actor string) (*Set, error)
Create inserts a set and records it in the audit log.
func (*Store) GetResolution ¶
GetResolution returns a stored resolution, or nil.
func (*Store) Recheck ¶
func (s *Store) Recheck(ctx context.Context, tx pgx.Tx, setID string) (*Set, *Resolution, bool, error)
Recheck recomputes a set's resolution inside tx and reports whether its id differs from the last one recorded. The row lock serialises two changes to one set, so each sees the other's result. A changed id is saved in the same transaction, so a consumer told of it can fetch it at once.
func (*Store) RecordCaller ¶
func (s *Store) RecordCaller(ctx context.Context, set *Set, userID, name, resolutionID string) error
RecordCaller notes the last use of a set by a key's identity.
func (*Store) SaveResolution ¶
SaveResolution stores a resolution. The row for an id never changes.
func (*Store) SetNotifier ¶
func (s *Store) SetNotifier(n ChangeNotifier)
SetNotifier attaches the receiver of set edits.
func (*Store) SkillVersionExists ¶
SkillVersionExists supports validating an entry at edit time.