format

type Accepted struct {
	Status int
}

type Admitter interface {
	Admit(ctx context.Context, env Env, c repo.Config, w Write) (Write, error)
}

type Annotation struct {
	// Set holds the keys set or replaced, with their new values.
	Set types.Properties
	// Removed lists the keys removed.
	Removed []string
	// At is when the change was made. A hook that writes properties in
	// turn writes them at At, so they read as part of the same change
	// (types.Item.PropertiesModified) rather than a later one.
	At time.Time
}

type Annotator interface {
	Annotated(ctx context.Context, env Env, c repo.Config, it types.Item, a Annotation) error
}

type Blobs interface {
	// Open returns the content stored under a SHA-256 for random access;
	// the caller closes it.
	Open(ctx context.Context, sha256 string) (io.ReadSeekCloser, blob.Info, error)
	// Stat returns a blob's Info without opening it.
	Stat(ctx context.Context, sha256 string) (blob.Info, error)
}

type Class int

type Classifier interface {
	Classify(c repo.Config, path string) Class
}

type Derived struct {
	Repo   repo.Config
	Cached bool
	// Path is repository-relative, without a leading slash.
	Path       string
	Body       io.Reader
	Properties types.Properties
	// By is recorded as the item's creator and modifier.
	By string
}

type Download struct {
	// Path is the requested repository-relative path.
	Path   string
	Cached bool
	// Matrix holds the request's matrix parameters, which the file served
	// must match.
	Matrix types.Matrix
	// Readable reports whether the caller may read a file of the
	// repository; nil reads every file.
	Readable func(fullPath string) bool
}

type Env struct {
	// Store is the metadata store.
	Store store.Store
	// Blobs reads stored content, such as the file a hook indexes. Formats
	// write content only through Derive and remove it only through
	// Underive.
	Blobs Blobs
	// Now is the clock.
	Now func() time.Time
	// Layouts resolves repository layouts by name, compiling each at most
	// once per operation.
	Layouts Layouts
	// Derive writes a derived item, such as maven-metadata.xml, inside the
	// current transaction without calling any hook, so a format's own
	// output never re-enters it. A format must not derive an item another
	// format would need to index.
	Derive func(ctx context.Context, d Derived) (types.Item, error)
	// Underive removes the file at path, which the format derived, without
	// any hook and past the trash can, releasing its content; nothing at
	// path is no error. A restore would bring back data the format
	// recomputes anyway.
	Underive func(ctx context.Context, c repo.Config, cached bool, path string) error
	// Remove deletes the files at paths, of c's own content, as a client's
	// delete does: through every hook, the format's own included, and into
	// the trash can when it is on, recorded as deleted by by. It then
	// prunes the folders those deletes left empty, up to the repository
	// root. A path with nothing at it is skipped. It is one transaction, so
	// a failure removes none. Derived work removes deployed files with it,
	// such as Maven's maxUniqueSnapshots cleanup.
	Remove func(ctx context.Context, c repo.Config, paths []string, by string) error
	// Enqueue asks the persistent work queue for kind's work on key
	// (decision 0033). Called with a hook's ctx, the work is asked for
	// exactly when the write commits, and not at all after a rollback.
	Enqueue func(ctx context.Context, kind, key string, payload []byte) error
	// Move moves the file at from to to, both in c, as a move by the REST
	// API makes it, with every hook, by as its mover, and never over an
	// item at to. It returns why the file did not move, or "" once it has.
	// It is for a format's Work, such as npm's strict-layout conversion,
	// which moves files a client stored where the format cannot index them.
	Move func(ctx context.Context, c repo.Config, from, to, by string) (string, error)
	// Inspection is what the format's Inspect returned for the file being
	// written. It is nil when the format inspects nothing, and on a
	// restore, which runs inside its caller's transaction: a hook that needs
	// one then inspects the content itself.
	Inspection any
}

type Handler interface {
	// Deployed runs after a file was stored at it (new or overwritten), by a
	// deploy, a copy, a move or a restore, once its properties are set.
	Deployed(ctx context.Context, env Env, c repo.Config, it types.Item) error
	// Deleting runs for each file before it is removed from the tree.
	Deleting(ctx context.Context, env Env, c repo.Config, it types.Item) error
	// Deleted runs once after a delete or a move removed items from the tree
	// and the item service pruned the versions left without files. A format
	// whose versions or packages depend on more than their own files (a
	// Docker tag exists while its folder holds a manifest) corrects the
	// index here.
	Deleted(ctx context.Context, env Env, c repo.Config, removed []types.Item) error
}

type Inspector interface {
	Inspect(ctx context.Context, env Env, c repo.Config, w Write) (any, error)
}

type Layouts interface {
	Layout(ctx context.Context, name string) (*layout.Layout, error)
}

type Op int

type Reindexer interface {
	Reindex(ctx context.Context, env Env, c repo.Config) error
}

type Rejection struct {
	Status  int
	Message string
}

type Resolver interface {
	Resolve(ctx context.Context, env Env, c repo.Config, d Download) (string, error)
}

type SidecarOwner interface {
	OwnsSidecars()
}

type WorkRef struct {
	Kind, Key string
}

type Worker interface {
	// WorkKinds are the kinds the format enqueues: code constants, unique
	// across formats.
	WorkKinds() []string
	// Work runs one item of one of the format's kinds, outside any
	// transaction. It must be idempotent and read the state it derives from
	// afresh, since an item can run again and coalesces every request made
	// before the run began.
	Work(ctx context.Context, env Env, item types.WorkItem) error
	// Owed names the work a download of path from c must see done before
	// it is read, so a client never reads derived data that lags a
	// completed write.
	Owed(c repo.Config, cached bool, path string) []WorkRef
}

type Write struct {
	Op Op
	// Path is the repository-relative target. Admit may change it, and the
	// write then lands there.
	Path   string
	Cached bool
	// Properties are set on the item with the write: a deploy's matrix
	// parameters, or the properties a copy or move carries over. Admit may
	// add or change them.
	Properties types.Properties
	// Size and Checksums describe the content. For OpChecksum, Checksums is
	// empty and Size is the length of the sidecar's body as the client
	// declared it, or -1.
	Size      int64
	Checksums types.Checksums
	// From is the source of a copy or move.
	From types.Item
}