source

type Adapter ¶

type Adapter interface {
	Kind() basespec.SourceKind

	NormalizeConfig(
		ctx context.Context,
		raw json.RawMessage,
	) (json.RawMessage, error)

	Open(
		ctx context.Context,
		value Source,
	) (Snapshot, error)
}

type Draft ¶

type Draft struct {
	ID          basespec.SourceID   `json:"id"`
	StorageKey  basespec.StorageKey `json:"storageKey"`
	Kind        basespec.SourceKind `json:"kind"`
	DisplayName string              `json:"displayName"`
	Enabled     bool                `json:"enabled"`
	Config      json.RawMessage     `json:"config"`
}

type Entry ¶

type Entry struct {
	Locator    basespec.Locator
	Name       string
	SizeBytes  int64
	Mode       uint32
	ModifiedAt time.Time

	IsDirectory bool
	IsRegular   bool
}

func (e Entry) Validate() error

type LocalPathCapability ¶ added in v0.2.13

type LocalPathCapability interface {
	SupportsLocalPath(
		kind basespec.SourceKind,
	) bool
}

LocalPathCapability advertises which Source kinds can provide trusted native paths. It avoids consumer hard-coding of concrete adapter kinds.

type LocalPathResolver ¶ added in v0.2.11

type LocalPathResolver interface {
	ResolveLocalPath(
		ctx context.Context,
		value Source,
		locator basespec.Locator,
	) (string, error)
}

LocalPathResolver is an optional trusted internal capability exposed by a Source adapter when a source-relative locator has a native local filesystem representation.

It is deliberately not part of Snapshot and is never exposed through public source summaries or Workspace API views. Consumers use it only after their own runtime policy has approved a selected record.

type LocalPathRuntime ¶ added in v0.2.11

type LocalPathRuntime interface {
	ResolveLocalPath(
		ctx context.Context,
		value Source,
		locator basespec.Locator,
	) (string, error)

	SupportsLocalPath(
		kind basespec.SourceKind,
	) bool
}

LocalPathRuntime is an optional extension implemented by the trusted source runtime when its opener supports LocalPathResolver.

It intentionally accepts a full Source rather than a public Summary because source configuration remains internal to Artifact Store consumers.

type ManagedPackageAddress ¶ added in v0.2.17

type ManagedPackageAddress struct {
	Kind    basespec.PackageKind    `json:"kind"`
	Name    basespec.LogicalName    `json:"name"`
	Version basespec.LogicalVersion `json:"version"`
}

ManagedPackageAddress is the generic semantic address of one complete managed package.

Artifact Store owns only this three-segment address shape:

<kind>/<name>/<version>

Artifact families own the values of Kind, Name, Version, all primary file names, and all package-relative resource conventions.

func NewManagedPackageAddress(
	kind basespec.PackageKind,
	name basespec.LogicalName,
	version basespec.LogicalVersion,
) (ManagedPackageAddress, error)

func ParseManagedPackageAddressDirectory(
	directory basespec.Locator,
) (ManagedPackageAddress, error)

func (a ManagedPackageAddress) Directory() (basespec.Locator, error)

func (a ManagedPackageAddress) FileLocator(
	relative basespec.Locator,
) (basespec.Locator, error)

func (a ManagedPackageAddress) Validate() error

type ManagedPackageFile ¶ added in v0.2.13

type ManagedPackageFile struct {
	Locator basespec.Locator `json:"locator"`
	Content []byte           `json:"content"`
}

ManagedPackageFile is one regular file relative to a managed package root. Empty directories are deliberately not represented.

func NormalizeManagedPackageFiles(
	input []ManagedPackageFile,
) ([]ManagedPackageFile, error)

type ManagedPackagePublication ¶ added in v0.2.13

type ManagedPackagePublication struct {
	Address            ManagedPackageAddress `json:"address"`
	ExpectedGeneration string                `json:"expectedGeneration,omitempty"`
	Files              []ManagedPackageFile  `json:"files"`
}

ManagedPackagePublication atomically publishes one package at one semantic address. ExpectedGeneration is optional for creation and required by callers that intentionally replace existing package content.

func NormalizeManagedPackagePublication(
	input ManagedPackagePublication,
) (ManagedPackagePublication, error)

type ManagedPackageWriter ¶ added in v0.2.13

type ManagedPackageWriter interface {
	PublishPackage(
		ctx context.Context,
		value Source,
		publication ManagedPackagePublication,
	) (generation string, err error)

	RemovePackage(
		ctx context.Context,
		value Source,
		address ManagedPackageAddress,
		expectedGeneration string,
	) error
}

ManagedPackageWriter is the optional writable capability for an application-managed Source adapter.

It deliberately publishes complete package directories rather than arbitrary individual file mutations. This gives managed authoring a staged, source-side atomic publication boundary without pretending that the Source filesystem and metadata database share one transaction.

type ManagedRootRemover ¶ added in v0.2.15

type ManagedRootRemover interface {
	RemoveManagedRoot(
		ctx context.Context,
		rootStorageKey basespec.StorageKey,
	) error
}

ManagedRootRemover is a trusted adapter capability used only when an application-owned topology is being replaced as a whole. It removes all managed Source storage below one Root, including packages that are no longer declared by a newer binary.

It must never be exposed through public Source APIs.

type ManagedSourceBootstrapper ¶ added in v0.2.13

type ManagedSourceBootstrapper interface {
	BootstrapManagedSource(
		ctx context.Context,
		value Source,
	) error

	DiscardBootstrappedManagedSource(
		ctx context.Context,
		value Source,
	) error
}

ManagedSourceBootstrapper is an optional capability implemented by writable Source adapters that need to establish physical Source storage before the Source metadata row is published.

DiscardBootstrappedManagedSource is used for failed source provisioning and for discarding a bundle-owned Source after all published packages were removed. It must refuse to remove published package content, but may remove adapter-private staging state.

type Opener ¶

type Opener interface {
	Open(
		ctx context.Context,
		value Source,
	) (Snapshot, error)
}

type Reader ¶

type Reader interface {
	Get(
		ctx context.Context,
		rootID basespec.RootID,
		id basespec.SourceID,
	) (Source, error)
}

type Registry ¶

type Registry struct {
	// contains filtered or unexported fields
}

func NewRegistry(adapters ...Adapter) (*Registry, error)

func (r *Registry) Kinds() []basespec.SourceKind

func (r *Registry) Open(
	ctx context.Context,
	value Source,
) (Snapshot, error)

func (r *Registry) PublishPackage(
	ctx context.Context,
	value Source,
	publication ManagedPackagePublication,
) (string, error)

func (r *Registry) RemoveManagedRoot(
	ctx context.Context,
	rootStorageKey basespec.StorageKey,
) error

func (r *Registry) RemovePackage(
	ctx context.Context,
	value Source,
	address ManagedPackageAddress,
	expectedGeneration string,
) error

func (r *Registry) ResolveLocalPath(
	ctx context.Context,
	value Source,
	locator basespec.Locator,
) (string, error)

func (r *Registry) SupportsLocalPath(
	kind basespec.SourceKind,
) bool

func (r *Registry) SupportsManagedPackages(
	kind basespec.SourceKind,
) bool

type Repository ¶

type Repository interface {
	Reader

	Create(
		ctx context.Context,
		value Source,
	) error

	List(
		ctx context.Context,
		rootID basespec.RootID,
	) ([]Source, error)

	Update(
		ctx context.Context,
		value Source,
		expectedRevision uint64,
	) error

	Retire(
		ctx context.Context,
		value Source,
		expectedRevision uint64,
	) error

	Discard(
		ctx context.Context,
		rootID basespec.RootID,
		id basespec.SourceID,
		expectedRevision uint64,
	) error

	Purge(
		ctx context.Context,
		rootID basespec.RootID,
		id basespec.SourceID,
		expectedRevision uint64,
	) error
}

type Runtime ¶

type Runtime interface {
	Get(
		ctx context.Context,
		rootID basespec.RootID,
		id basespec.SourceID,
	) (Source, error)

	Open(
		ctx context.Context,
		value Source,
	) (Snapshot, error)
}

Runtime is a trusted internal capability for consumers that need an operational source, including its normalized adapter configuration.

It is intentionally separate from Service, whose query methods return Summary values and do not expose opaque source configuration.

func NewRuntime(
	reader Reader,
	opener Opener,
) (Runtime, error)

type Service ¶

type Service struct {
	// contains filtered or unexported fields
}

func NewService(
	repository Repository,
	registry *Registry,
	roots rootReader,
	timeClock clockutil.Clock,
	policy protection.RootPolicy,
) (*Service, error)

func (s *Service) Create(
	ctx context.Context,
	rootID basespec.RootID,
	draft Draft,
) (Summary, error)

func (s *Service) CreateWithStatus(
	ctx context.Context,
	rootID basespec.RootID,
	draft Draft,
) (Summary, bool, error)

func (s *Service) Discard(
	ctx context.Context,
	rootID basespec.RootID,
	id basespec.SourceID,
	expectedRevision uint64,
) error

func (s *Service) Get(
	ctx context.Context,
	rootID basespec.RootID,
	id basespec.SourceID,
) (Summary, error)

func (s *Service) Kinds() []basespec.SourceKind

func (s *Service) List(
	ctx context.Context,
	rootID basespec.RootID,
) ([]Summary, error)

func (s *Service) MarkContentChanged(
	ctx context.Context,
	rootID basespec.RootID,
	id basespec.SourceID,
	expectedRevision uint64,
) (Summary, error)

func (s *Service) Purge(
	ctx context.Context,
	rootID basespec.RootID,
	id basespec.SourceID,
	expectedRevision uint64,
) error

func (s *Service) Retire(
	ctx context.Context,
	rootID basespec.RootID,
	id basespec.SourceID,
	expectedRevision uint64,
) (Summary, error)

func (s *Service) Update(
	ctx context.Context,
	rootID basespec.RootID,
	id basespec.SourceID,
	update Update,
) (Summary, error)

type Snapshot ¶

type Snapshot interface {
	Generation() string

	Stat(
		ctx context.Context,
		locator basespec.Locator,
	) (Entry, error)

	ReadDir(
		ctx context.Context,
		locator basespec.Locator,
	) ([]Entry, error)

	Open(
		ctx context.Context,
		locator basespec.Locator,
	) (io.ReadCloser, error)

	Confirm(ctx context.Context) error
	Close() error
}

type Source ¶

type Source struct {
	ID             basespec.SourceID   `json:"id"`
	RootID         basespec.RootID     `json:"rootID"`
	RootStorageKey basespec.StorageKey `json:"rootStorageKey"`
	StorageKey     basespec.StorageKey `json:"storageKey"`
	Kind           basespec.SourceKind `json:"kind"`
	DisplayName    string              `json:"displayName"`
	Enabled        bool                `json:"enabled"`
	Config         json.RawMessage     `json:"-"`

	Revision   uint64     `json:"revision"`
	CreatedAt  time.Time  `json:"createdAt"`
	ModifiedAt time.Time  `json:"modifiedAt"`
	RetiredAt  *time.Time `json:"retiredAt,omitempty"`
}

func (s Source) Clone() Source

func (s Source) Summary() Summary

func (s Source) Validate() error

type Summary ¶

type Summary struct {
	ID             basespec.SourceID   `json:"id"`
	RootID         basespec.RootID     `json:"rootID"`
	RootStorageKey basespec.StorageKey `json:"rootStorageKey"`
	StorageKey     basespec.StorageKey `json:"storageKey"`
	Kind           basespec.SourceKind `json:"kind"`
	DisplayName    string              `json:"displayName"`
	Enabled        bool                `json:"enabled"`
	Revision       uint64              `json:"revision"`
	CreatedAt      time.Time           `json:"createdAt"`
	ModifiedAt     time.Time           `json:"modifiedAt"`
	RetiredAt      *time.Time          `json:"retiredAt,omitempty"`
}

func (s Summary) Validate() error

type Update ¶

type Update struct {
	ExpectedRevision uint64
	DisplayName      string
	Enabled          bool

	// Config is write-only replacement configuration. A nil value preserves
	// the current normalized configuration so public callers can update Source
	// metadata without reading or resending private Source configuration.
	Config json.RawMessage
}

type VerificationSession ¶ added in v0.2.16

type VerificationSession struct {
	// contains filtered or unexported fields
}

VerificationSession reuses verified Source snapshots while one caller resolves multiple local paths from the same catalogued Source generation.

Snapshot operations are intentionally serialized because Snapshot adapters are not required to support concurrent use.

func NewVerificationSession(
	ctx context.Context,
) (context.Context, *VerificationSession, error)

func (s *VerificationSession) Close(ctx context.Context) error