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
	Kind        basespec.SourceKind
	DisplayName string
	Enabled     bool
	Config      json.RawMessage
}

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 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 directory. Empty directories are deliberately not part of the managed package contract.

type ManagedPackagePublication ¶ added in v0.2.13

type ManagedPackagePublication struct {
	Directory          basespec.Locator     `json:"directory"`
	ExpectedGeneration string               `json:"expectedGeneration,omitempty"`
	Files              []ManagedPackageFile `json:"files"`
}

ManagedPackagePublication atomically publishes one new package directory inside a managed Source.

ExpectedGeneration is optional. When supplied, it prevents publication against a Source snapshot other than the one observed by the caller. Repeating an already completed, byte-identical publication is idempotent even when ExpectedGeneration names the generation before that publication.

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,
		directory basespec.Locator,
		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,
		rootID basespec.RootID,
	) 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,
	rootID basespec.RootID,
) error

func (r *Registry) RemovePackage(
	ctx context.Context,
	value Source,
	directory basespec.Locator,
	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,
	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"`
	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"`
	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