providerapi

package
v0.2.20 Latest Latest
Warning

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

 Go to latest Published: Sep 5, 2026 License: MPL-2.0 Imports: 16 Imported by: 0

Documentation

Overview

Package providerapi defines Artifact Store's stable inbound provider contracts.

Providers may depend on this package and basespec only from artifactstore.

Index

Constants

View Source 
const (
	MaxDiagnosticCodeBytes    = 128
	MaxDiagnosticMessageBytes = 4096
	MaxDiagnostics            = 128
)

Variables

This section is empty.

Functions

func BoundedDiagnosticMessage 

func BoundedDiagnosticMessage(value string) string

BoundedDiagnosticMessage converts dynamically generated text into a value accepted by Diagnostic.Validate. It is intended for internal errors whose text can contain untrusted JSON keys, paths, or decoder output.

func ContainsErrorDiagnostic 

func ContainsErrorDiagnostic(values []Diagnostic) bool

func DecodeBody 

func DecodeBody[T any](raw json.RawMessage) (T, error)

func EncodeBody 

func EncodeBody(value any) (json.RawMessage, error)

func EqualDiagnostics 

func EqualDiagnostics(left, right []Diagnostic) bool

func ValidateCollectionBehavior 

func ValidateCollectionBehavior(
	behavior CollectionBehavior,
) error

func ValidateDiagnostics 

func ValidateDiagnostics(values []Diagnostic) error

Types

type AdoptionDecision 

type AdoptionDecision struct {
	Adopt       bool
	Name        string
	Enabled     bool
	Data        json.RawMessage
	Diagnostics []Diagnostic
}

AdoptionDecision is provider-owned semantic intent. Artifact Store owns artifact ID generation, artifact construction, validation, persistence, reconciliation, revisions, and timestamps.

func (AdoptionDecision) Clone 

func (d AdoptionDecision) Clone() AdoptionDecision

func (AdoptionDecision) Validate 

func (d AdoptionDecision) Validate() error

type AdoptionInput 

type AdoptionInput struct {
	Collection Collection
	Attachment Attachment
	Occurrence Occurrence
	Definition Definition
}

AdoptionInput contains one valid source occurrence that Artifact Store is considering for automatic artifact adoption.

func (AdoptionInput) Clone 

func (i AdoptionInput) Clone() AdoptionInput

type Attachment 

type Attachment struct {
	RootID       basespec.RootID         `json:"rootID"`
	CollectionID basespec.CollectionID   `json:"collectionID"`
	SourceID     basespec.SourceID       `json:"sourceID"`
	Role         basespec.AttachmentRole `json:"role"`
	Enabled      bool                    `json:"enabled"`
	Revision     uint64                  `json:"revision"`
	Data         json.RawMessage         `json:"data"`
}

Attachment is a provider-safe view of a persisted Collection attachment.

func (Attachment) Clone 

func (a Attachment) Clone() Attachment

type Candidate 

type Candidate struct {
	SourceID            basespec.SourceID
	SourceKind          basespec.SourceKind
	Locator             basespec.Locator
	SourceContentDigest cryptoutil.Digest
	Content             []byte
	RequestedDecoderIDs []basespec.DecoderID
}

Candidate is one bounded source entry selected by Artifact Store discovery.

Artifact Store owns snapshot opening, bounded reads, source-content digest calculation, and source generation confirmation. A decoder receives only the candidate bytes and generic source identity.

func (Candidate) RequestsDecoder 

func (c Candidate) RequestsDecoder(id basespec.DecoderID) bool

type Collection 

type Collection struct {
	ID          basespec.CollectionID   `json:"id"`
	RootID      basespec.RootID         `json:"rootID"`
	Kind        basespec.CollectionKind `json:"kind"`
	DisplayName string                  `json:"displayName"`
	Description string                  `json:"description,omitempty"`
	Enabled     bool                    `json:"enabled"`
	Revision    uint64                  `json:"revision"`
	Data        json.RawMessage         `json:"data"`
}

Collection is a provider-safe view of a persisted Collection.

It deliberately excludes repositories, SQLite handles, source config, and feature-private runtime state.

func (Collection) Clone 

func (c Collection) Clone() Collection

type CollectionBehavior 

type CollectionBehavior interface {
	CollectionKind() basespec.CollectionKind

	// Revision must change whenever provider behavior can alter discovery
	// scope, decoder selection, automatic-adoption eligibility, or default
	// local artifact data.
	Revision() string

	DecideAutomaticAdoption(
		ctx context.Context,
		input AdoptionInput,
	) (AdoptionDecision, error)
}

CollectionBehavior is the common Artifact Store inbound behavior for one CollectionKind. A behavior must additionally implement exactly one planning role below.

It receives immutable generic views and returns declarations. It must not perform direct Artifact Store mutations or depend on system.Components.

type CollectionPlanner 

type CollectionPlanner interface {
	CollectionBehavior

	BuildDiscoveryPlan(
		ctx context.Context,
		collection Collection,
		attachments []Attachment,
		sources []Source,
	) (Plan, error)
}

CollectionPlanner is the normal provider planning role. It receives only persisted generic views and returns a declarative discovery plan.

type Decoded 

type Decoded struct {
	SubresourceLocator basespec.SubresourceLocator
	Definition         Definition
	Diagnostics        []Diagnostic
}

Decoded is one provider-derived definition emitted from a source candidate.

type Decoder 

type Decoder interface {
	ID() basespec.DecoderID
	Revision() string

	Recognize(
		ctx context.Context,
		candidate Candidate,
	) Recognition

	Decode(
		ctx context.Context,
		candidate Candidate,
	) ([]Decoded, []Diagnostic)
}

Decoder is an Artifact Store inbound content-decoding plugin.

Artifact Store owns decoder selection, read limits, content hashing, occurrence state transitions, definition persistence, and catalog publication. The decoder owns format recognition and semantic projection.

type DecoderHint 

type DecoderHint struct {
	Locator    basespec.Locator     `json:"locator"`
	Recursive  bool                 `json:"recursive"`
	DecoderIDs []basespec.DecoderID `json:"decoderIDs"`
}

DecoderHint identifies decoders preferred for a source-relative scope.

func (DecoderHint) Clone 

func (h DecoderHint) Clone() DecoderHint

type Definition 

type Definition struct {
	Digest         cryptoutil.Digest       `json:"digest"`
	Kind           basespec.ArtifactKind   `json:"kind"`
	SchemaID       basespec.SchemaID       `json:"schemaID"`
	SchemaVersion  string                  `json:"schemaVersion"`
	LogicalName    basespec.LogicalName    `json:"logicalName"`
	LogicalVersion basespec.LogicalVersion `json:"logicalVersion,omitempty"`
	DisplayName    string                  `json:"displayName,omitempty"`
	Description    string                  `json:"description,omitempty"`
	Labels         map[string]string       `json:"labels,omitempty"`
	Body           json.RawMessage         `json:"body"`
	Dependencies   []Selector              `json:"dependencies,omitempty"`
}

Definition is a canonical derived Artifact definition.

Digest is a canonical content fingerprint used for integrity, comparison, and source-state reconciliation. It is not a storage address. Persisted definitions are keyed by their current catalog occurrence.

func Canonicalize 

func Canonicalize(input Definition) (Definition, error)

func (Definition) Clone 

func (d Definition) Clone() Definition

func (Definition) Validate 

func (d Definition) Validate() error

type Descriptor 

type Descriptor struct {
	Name string

	CollectionBehaviors []CollectionBehavior
	Schemas             []SchemaCodec
	Decoders            []Decoder
}

Descriptor is immutable provider registration metadata.

CollectionKinds establishes exclusive ownership of persisted collection kinds through executable CollectionBehavior implementations.

func (Descriptor) Clone 

func (d Descriptor) Clone() Descriptor

func (Descriptor) Validate 

func (d Descriptor) Validate() error

type Diagnostic 

type Diagnostic struct {
	Severity DiagnosticSeverity  `json:"severity"`
	Code     string              `json:"code"`
	Message  string              `json:"message"`
	Location *DiagnosticLocation `json:"location,omitempty"`
}

func AppendDiagnostics 

func AppendDiagnostics(
	current []Diagnostic,
	incoming ...Diagnostic,
) []Diagnostic

func CloneDiagnostics 

func CloneDiagnostics(values []Diagnostic) []Diagnostic

func (Diagnostic) Validate 

func (d Diagnostic) Validate() error

type DiagnosticLocation 

type DiagnosticLocation struct {
	Locator            basespec.Locator            `json:"locator,omitempty"`
	SubresourceLocator basespec.SubresourceLocator `json:"subresourceLocator,omitempty"`
	Line               int                         `json:"line,omitempty"`
	Column             int                         `json:"column,omitempty"`
}

type DiagnosticSeverity 

type DiagnosticSeverity string
const (
	DiagnosticError   DiagnosticSeverity = "error"
	DiagnosticWarning DiagnosticSeverity = "warning"
	DiagnosticInfo    DiagnosticSeverity = "info"
)

type DirectoryRoot 

type DirectoryRoot struct {
	Root            basespec.Locator `json:"root"`
	Recursive       bool             `json:"recursive"`
	IncludePatterns []string         `json:"includePatterns,omitempty"`
}

DirectoryRoot declares one source-relative directory discovery scope.

func (DirectoryRoot) Clone 

func (r DirectoryRoot) Clone() DirectoryRoot

func (DirectoryRoot) Validate 

func (r DirectoryRoot) Validate() error

type DocumentPlanningBehavior 

type DocumentPlanningBehavior interface {
	CollectionBehavior

	BuildDiscoveryPlanWithDocuments(
		ctx context.Context,
		collection Collection,
		attachments []Attachment,
		sources []Source,
		documents PlanningDocumentReader,
	) (Plan, error)
}

DocumentPlanningBehavior is the exceptional planning role for collection kinds whose declared discovery scope depends on one source-owned canonical document. Workspace implements this for workspace.json.

The supplied reader is intentionally narrower than source.Runtime. It can read only canonical documents through Artifact Store controls.

type EntityCanonicalizer 

type EntityCanonicalizer interface {
	CanonicalizeEntity(
		ctx context.Context,
		entity EntityType,
		raw []byte,
	) (ParsedDocument, error)
}

EntityCanonicalizer supports dispatch by an entity type inferred from a caller-owned context.

type EntityType 

type EntityType string
const (
	EntityCollection EntityType = "collection"
	EntityArtifact   EntityType = "artifact"
)

type ExpectedCanonicalizer 

type ExpectedCanonicalizer interface {
	CanonicalizeExpected(
		ctx context.Context,
		expected SchemaKey,
		raw []byte,
	) (ParsedDocument, error)
}

ExpectedCanonicalizer is the narrow Artifact Store capability required by a provider that accepts a document with a known schema identity.

type Occurrence 

type Occurrence struct {
	RootID             basespec.RootID             `json:"rootID"`
	CollectionID       basespec.CollectionID       `json:"collectionID"`
	SourceID           basespec.SourceID           `json:"sourceID"`
	Locator            basespec.Locator            `json:"locator"`
	SubresourceLocator basespec.SubresourceLocator `json:"subresourceLocator,omitempty"`
	Kind               basespec.ArtifactKind       `json:"kind"`
}

Occurrence is the provider-safe observation supplied to automatic adoption.

type ParsedDocument 

type ParsedDocument struct {
	Key    SchemaKey
	Digest cryptoutil.Digest
	Raw    json.RawMessage
}

ParsedDocument is a canonical document accepted by a registered schema codec.

func (ParsedDocument) Clone 

func (d ParsedDocument) Clone() ParsedDocument

func (ParsedDocument) Validate 

func (d ParsedDocument) Validate() error

type Plan 

type Plan struct {
	// Revision identifies provider-owned discovery behavior. Artifact Store
	// includes it in the catalog plan fingerprint.
	Revision string       `json:"revision,omitempty"`
	Sources  []SourcePlan `json:"sources"`
}

Plan is a provider-owned declaration of source discovery scope.

Artifact Store validates and converts this contract into its internal discovery.Plan before it opens source snapshots or publishes a catalog.

func (Plan) Clone 

func (p Plan) Clone() Plan

func (Plan) Fingerprint 

func (p Plan) Fingerprint() (cryptoutil.Digest, error)

Fingerprint returns the same semantic discovery fingerprint shape used by Artifact Store's internal discovery.Plan. ExpectedGeneration is deliberately excluded because it is a concurrency token rather than a capability input.

func (Plan) Normalized 

func (p Plan) Normalized() Plan

Normalized returns an independently owned deterministic plan.

func (Plan) Validate 

func (p Plan) Validate() error

type PlanningDocument 

type PlanningDocument struct {
	SourceID   basespec.SourceID
	Generation string
	Found      bool
	Document   *ParsedDocument
}

PlanningDocument is a Store-verified result of a planning document read.

A missing document is represented by Found=false and Document=nil. The confirmed Source generation is returned in both the found and missing cases so the provider can place it into the resulting SourcePlan as an optimistic precondition.

func (PlanningDocument) Clone 

func (d PlanningDocument) Clone() PlanningDocument

func (PlanningDocument) Validate 

func (d PlanningDocument) Validate() error

type PlanningDocumentReader 

type PlanningDocumentReader interface {
	ReadCanonicalDocument(
		ctx context.Context,
		request PlanningDocumentRequest,
	) (PlanningDocument, error)
}

PlanningDocumentReader is the only source-read capability available to a document-aware collection planner.

Artifact Store validates that the requested Source is attached to the Collection, opens and confirms the snapshot, bounds the read, dispatches the expected schema codec, and closes the snapshot. Providers never receive source configuration, source paths, a Snapshot, or raw filesystem access.

type PlanningDocumentRequest 

type PlanningDocumentRequest struct {
	SourceID       basespec.SourceID
	Locator        basespec.Locator
	ExpectedSchema SchemaKey
}

PlanningDocumentRequest identifies one source-relative portable document needed to derive a provider discovery plan.

func (PlanningDocumentRequest) Validate 

func (r PlanningDocumentRequest) Validate() error

type Provider 

type Provider interface {
	Descriptor() Descriptor
}

Provider is one Artifact Store inbound artifact-family registration.

It registers schemas, decoders, and collection-kind behavior without requiring Artifact Store to import the concrete provider package.

type Recognition 

type Recognition int
const (
	RecognitionNone Recognition = iota
	RecognitionPossible
	RecognitionPreferred
)

type SchemaCanonicalizerBinder 

type SchemaCanonicalizerBinder interface {
	RequiredSchemaKeys() []SchemaKey

	BindExpectedCanonicalizer(
		schemas SchemaCatalog,
	) error
}

SchemaCanonicalizerBinder is optional. A decoder implements it when its source bytes must be canonicalized through the registered Artifact Store schema catalog before the decoder can project definitions.

This replaces direct decoder dependencies on *shareable.Registry.

type SchemaCatalog 

type SchemaCatalog interface {
	ExpectedCanonicalizer

	Keys() []SchemaKey
}

SchemaCatalog is the narrow setup-time capability supplied to a decoder that must canonicalize source documents through Artifact Store's schema registry.

It deliberately exposes only known keys and expected-schema canonicalization. It does not expose concrete registry implementation, database access, or Artifact Store services.

type SchemaCodec 

type SchemaCodec interface {
	Key() SchemaKey
	JSONSchema() []byte

	Canonicalize(
		ctx context.Context,
		raw []byte,
	) (ParsedDocument, error)
}

SchemaCodec supplies one published JSON Schema and domain-specific semantic canonicalization.

Artifact Store owns schema registration, schema execution, registry dispatch, canonical JSON checks, and output verification. The provider owns only its schema semantics and canonicalization rules.

type SchemaKey 

type SchemaKey struct {
	Entity        EntityType        `json:"entity"`
	Kind          SchemaKind        `json:"kind"`
	SchemaID      basespec.SchemaID `json:"schemaID"`
	SchemaVersion string            `json:"schemaVersion"`
}

func ArtifactSchemaKey 

func ArtifactSchemaKey(
	kind basespec.ArtifactKind,
	schemaID basespec.SchemaID,
	schemaVersion string,
) SchemaKey

func CollectionSchemaKey 

func CollectionSchemaKey(
	kind basespec.CollectionKind,
	schemaID basespec.SchemaID,
	schemaVersion string,
) SchemaKey

func (SchemaKey) Validate 

func (k SchemaKey) Validate() error

type SchemaKind 

type SchemaKind string

SchemaKind is the entity-neutral kind portion of a schema key.

A SchemaKind intentionally does not imply either CollectionKind or ArtifactKind. The Entity field establishes which validation rule applies.

type Selector 

type Selector struct {
	Kind              basespec.ArtifactKind `json:"kind"`
	LogicalName       basespec.LogicalName  `json:"logicalName,omitempty"`
	VersionConstraint string                `json:"versionConstraint,omitempty"`
	Labels            map[string]string     `json:"labels,omitempty"`
}

func (Selector) Validate 

func (s Selector) Validate() error

type Source 

type Source struct {
	ID          basespec.SourceID   `json:"id"`
	RootID      basespec.RootID     `json:"rootID"`
	StorageKey  basespec.StorageKey `json:"storageKey"`
	Kind        basespec.SourceKind `json:"kind"`
	DisplayName string              `json:"displayName"`
	Enabled     bool                `json:"enabled"`
	Revision    uint64              `json:"revision"`
}

Source is a provider-safe summary of an attached Source.

It deliberately excludes Source.Config. A collection provider decides discovery semantics from source identity and kind, while Artifact Store owns source configuration, snapshot opening, and filesystem access.

type SourcePlan 

type SourcePlan struct {
	SourceID               basespec.SourceID                      `json:"sourceID"`
	ExplicitLocators       []basespec.Locator                     `json:"explicitLocators,omitempty"`
	DirectoryRoots         []DirectoryRoot                        `json:"directoryRoots,omitempty"`
	DecoderHints           []DecoderHint                          `json:"decoderHints,omitempty"`
	ExpectedContentDigests map[basespec.Locator]cryptoutil.Digest `json:"expectedContentDigests,omitempty"`
	ExpectedGeneration     string                                 `json:"expectedGeneration,omitempty"`
	AllowedDecoderIDs      []basespec.DecoderID                   `json:"allowedDecoderIDs,omitempty"`
	Authoritative          bool                                   `json:"authoritative"`
	MaxCandidateBytes      int64                                  `json:"maxCandidateBytes"`
	MaxTotalBytes          int64                                  `json:"maxTotalBytes"`
	MaxCandidates          int                                    `json:"maxCandidates"`
	MaxEntries             int                                    `json:"maxEntries"`
	MaxDepth               int                                    `json:"maxDepth"`
}

SourcePlan declares discovery scope for one attached Source.

func (SourcePlan) Clone 

func (p SourcePlan) Clone() SourcePlan

func (SourcePlan) Normalized 

func (p SourcePlan) Normalized() SourcePlan

Normalized returns an independently owned deterministic SourcePlan with Artifact Store discovery defaults applied.

func (SourcePlan) RequestedDecoderIDs 

func (p SourcePlan) RequestedDecoderIDs(
	locator basespec.Locator,
) []basespec.DecoderID

func (SourcePlan) Validate 

func (p SourcePlan) Validate() error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.