callerpublication

package
v0.0.0-...-3d6ecf2 Latest Latest
Warning

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

 Go to latest Published: Aug 25, 2026 License: Apache-2.0 Imports: 25 Imported by: 0

Documentation

Overview

Package callerpublication owns complete caller-generation visibility. Leaf artifacts remain independently durable and invisible until named by one validated complete manifest and matching store pointer.

Index

Constants

View Source 
const (
	MaxOmissionDetails = 64

	// The live installation cap accounts for leaf bytes. Keep independent
	// headroom for complete manifests, tar headers, and padding.
	MaxArchiveBytes = int64(4 << 40)
)
View Source 
const (
	MaxInstallationPublicationRefs = callerpublicationid.InstallationPublicationRefs
	MaxInstallationCanonicalBytes  = callerpublicationid.InstallationCanonicalBytes
	// A publication transition performs at most one bounded residue batch.
	// Further immutable residue remains non-authoritative and is resumed by a
	// later Observe/startup pass instead of turning a reader release or publish
	// into an installation-wide multi-terabyte manifest scan.
	MaxTransitionCleanupManifests = 32
	MaxTransitionCleanupPairRefs  = 65_536
)

Discovery retains parsed publication identities for its caller. Bound the cumulative manifest + leaf reference set independently of the per-repository directory cap so a wide installation cannot multiply memory without limit.

View Source 
const (
	ManifestSchema = "phebs-caller-generation-publication-manifest-v1"
	StateSchema    = "phebs-caller-generation-publication-state-v1"
	MarkerSchema   = "phebs-caller-generation-publication-marker-v1"

	MaxManifestBytes = 32 << 20
)
View Source 
const (
	// The registry is a parsed-state cache, not the durable authority. These
	// process-wide ceilings retain at most two maximum-size 16,384-pair
	// publications so one exact old/replacement comparison can hold both
	// immutable leases. Smaller publications may occupy the remaining identity
	// slots within the same pair-reference ceiling. Store-authoritative bytes
	// remain cold-openable.
	MaxRegistryPublications = 8
	MaxRegistryPairRefs     = 2 * callerleaf.MaxExpectedPairs
	// MaxConcurrentColdAdmissions bounds cross-repository manifest/leaf content
	// validation. Warm leases never enter this gate.
	MaxConcurrentColdAdmissions = 2

	// MaxRegistryAuthorityTokens is the installation-wide ceiling for compact
	// cleanup authority retained after parsed-state eviction. Each token is only
	// one cryptographic repository-directory name and one exact manifest
	// basename; the manifest reconstructs and validates the full cleanup receipt
	// on retirement. This matches the durable current-publication row ceiling.
	MaxRegistryAuthorityTokens = callerpublicationid.InstallationPublicationRepositories
	// MaxRegistryAuthorityIdentityBytes counts the fixed-length map key and
	// manifest-name payloads, excluding Go map/string headers. Both identities
	// are digest-derived and therefore have no input-dependent length.
	MaxRegistryAuthorityIdentityBytes = MaxRegistryAuthorityTokens *
		(len("phebs-caller-overlay-") + 64 +
			len(callerpublicationid.ManifestPrefix) + 64 + 1 + 64 +
			len(".manifest.json"))
)

Variables

View Source 
var (
	ErrInvalidManifest  = errors.New("invalid caller publication manifest")
	ErrPublishing       = errors.New("caller publication is in progress")
	ErrPublicationIO    = errors.New("caller publication I/O failure")
	ErrRegistryConflict = errors.New("caller publication registry has another current generation")
)

Functions

func AbandonPublishing 

func AbandonPublishing(
	ctx context.Context,
	root, repository string,
	keep *State,
) error

AbandonPublishing removes a failed prior-process marker. Eligible callers durably queue a forced successor first; startup may instead use it for an ineligible repository that cannot accept work. A decoded marked manifest is removed unless it is the explicitly retained current state.

func CleanupStages 

func CleanupStages(ctx context.Context, root string) (int, error)

CleanupStages removes only bounded package-shaped publication stages. It ignores leaf stages, immutable artifacts, and foreign entries.

func ClearPublishing 

func ClearPublishing(root string, expected State) error

ClearPublishing removes only a marker whose canonical payload matches the supplied exact state. A missing marker is idempotent.

func Discover 

func Discover(
	ctx context.Context,
	root string,
) ([]*Publication, DiscoveryReport, error)

Discover cold-validates every unambiguous, marker-free complete publication under its physical cryptographic owner. Multiple immutable manifests in one repository are a crash residue, not authority; offline discovery omits that repository rather than guessing which store pointer was current.

func IsRetentionArtifactName 

func IsRetentionArtifactName(name string) bool

IsRetentionArtifactName reports whether name is a complete-generation manifest or an immutable caller-leaf artifact.

func IsRetentionIgnoredControlName 

func IsRetentionIgnoredControlName(name string) bool

IsRetentionIgnoredControlName recognizes lifecycle-owned stages and markers which the retained-artifact component deliberately does not count.

func IsRetentionRepositoryDirectoryName 

func IsRetentionRepositoryDirectoryName(name string) bool

IsRetentionRepositoryDirectoryName recognizes the cryptographic directory namespace shared by complete manifests and independently durable leaves.

func Publishing 

func Publishing(root, repository string) (bool, error)

func ReconcileDeletionMarkers 

func ReconcileDeletionMarkers(
	ctx context.Context,
	root string,
	eligible func(context.Context, string) (bool, error),
) error

ReconcileDeletionMarkers closes the active-lease deletion crash edge. A valid ineligible tombstone still owns its package directory and removes it on the next startup. Same-name recreation clears only that exact tombstone. A deterministically incomplete tombstone cannot select a repository and is itself removed; operational I/O remains a startup failure.

func RemoveArtifactRefs 

func RemoveArtifactRefs(
	ctx context.Context,
	root string,
	manifest Manifest,
	removeManifest bool,
) error

RemoveArtifactRefs removes only exact derived basenames under the manifest's cryptographic repository owner. The caller must first establish that no active lease retains these leaf artifacts.

func RemoveManifest 

func RemoveManifest(root string, state State) error

RemoveManifest removes only one exact package-derived immutable manifest. Leaf retirement is separately lease-gated.

func RestoreArchive 

func RestoreArchive(archivePath, target string) error

RestoreArchive validates every header and complete publication in a private stage, then renames the complete filesystem set into an absent target.

func RestoreArchiveContext 

func RestoreArchiveContext(ctx context.Context, archivePath, target string) error

RestoreArchiveContext is the cancellable restore boundary. Cancellation can stop both the streaming semantic preflight and final staged extraction.

func ValidLeafArtifactName 

func ValidLeafArtifactName(name string) bool

func ValidRepositoryDirectoryName 

func ValidRepositoryDirectoryName(name string) bool

func ValidateManifest 

func ValidateManifest(manifest Manifest) error

func ValidateState 

func ValidateState(state State) error

Types

type ArchiveReport 

type ArchiveReport struct {
	Publications        int        `json:"publications"`
	OmittedPublications int        `json:"omitted_publications"`
	OmittedArtifacts    int        `json:"omitted_artifacts"`
	StaleMarkers        int        `json:"stale_markers"`
	Details             []Omission `json:"details,omitempty"`
	TruncatedDetails    int        `json:"truncated_details"`
}

ArchiveReport is a bounded receipt for derived state observed during backup. Counts remain exact; Details retains only the first fixed set.

func CreateArchiveWithReport 

func CreateArchiveWithReport(root, output string) (ArchiveReport, error)

CreateArchiveWithReport writes a deterministic archive containing every and only strictly valid, marker-free complete caller publication.

func CreateArchiveWithReportContext 

func CreateArchiveWithReportContext(
	ctx context.Context,
	root, output string,
) (ArchiveReport, error)

CreateArchiveWithReportContext is the cancellable backup boundary used by recovery. Every source read remains beneath the exact repository directory descriptor admitted by Discover; a path replacement can invalidate the backup, but cannot redirect its reads.

func VerifyArchiveWithReport 

func VerifyArchiveWithReport(archivePath string) (ArchiveReport, error)

VerifyArchiveWithReport streams the archive through the exact manifest and leaf validators without materializing a second publication tree.

func VerifyArchiveWithReportContext 

func VerifyArchiveWithReportContext(
	ctx context.Context,
	archivePath string,
) (ArchiveReport, error)

VerifyArchiveWithReportContext is the cancellable, O(one publication) memory and zero-scratch-disk archive verification boundary.

type ArtifactRef 

type ArtifactRef struct {
	RepositoryDirectory string `json:"repository_directory"`
	Name                string `json:"name"`
}

func ArtifactRefs 

func ArtifactRefs(manifest Manifest) []ArtifactRef

func (ArtifactRef) RelativePath 

func (reference ArtifactRef) RelativePath() string

type DiscoveryReport 

type DiscoveryReport struct {
	OmittedPublications int        `json:"omitted_publications"`
	OmittedArtifacts    int        `json:"omitted_artifacts"`
	StaleMarkers        int        `json:"stale_markers"`
	Details             []Omission `json:"details,omitempty"`
	TruncatedDetails    int        `json:"truncated_details"`
}

type Expected 

type Expected struct {
	Extractors []callerleaf.ExtractorIdentity
}

type Lease 

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

func (*Lease) Publication 

func (lease *Lease) Publication() *Publication

func (*Lease) ReadRecord 

func (lease *Lease) ReadRecord(
	ctx context.Context,
	reference RecordReference,
) (PairReceipt, callerleaf.Record, error)

ReadRecord reads and validates only the exact leased record named by a ScanRecords reference. It does not hash or materialize another record or leaf, making it suitable for bounded result-page hydration.

func (*Lease) Release 

func (lease *Lease) Release() (resultErr error)

func (*Lease) ScanRecords 

func (lease *Lease) ScanRecords(
	ctx context.Context,
	visit func(PairReceipt, RecordReference, callerleaf.Record) error,
) error

ScanRecords verifies every leaf in the leased complete generation exactly once and yields canonical records with exact bounded reread references. The visitor must discard any accumulated state when ScanRecords returns an error; the complete generation is not accepted until every leaf succeeds.

func (*Lease) State 

func (lease *Lease) State() State

type Manifest 

type Manifest struct {
	Schema        string                        `json:"schema"`
	Generation    callerleaf.GenerationIdentity `json:"generation"`
	PairSetDigest string                        `json:"pair_set_digest"`
	Pairs         []PairReceipt                 `json:"pairs"`
	Aggregate     callerleaf.AggregateReceipt   `json:"aggregate"`
	Digest        string                        `json:"digest"`
}

func BuildManifest 

func BuildManifest(
	generation callerleaf.GenerationIdentity,
	pairs []PairReceipt,
) (Manifest, error)

BuildManifest recomputes every semantic digest and aggregate from the exact ordered successful pair projection. Caller-supplied aggregate or digest values are never persisted.

func (Manifest) State 

func (manifest Manifest) State() State

type Omission 

type Omission struct {
	Name   string `json:"name"`
	Reason string `json:"reason"`
}

type PairReceipt 

type PairReceipt struct {
	Pair    callerleaf.PairIdentity `json:"pair"`
	Receipt callerleaf.Receipt      `json:"receipt"`
}

PairReceipt is the exact successful result artifact for one ordered caller domain/leaf pair. A complete manifest has no failure disposition: any missing or terminal pair prevents the manifest from being built.

type Prepared 

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

Prepared owns one bounded, synced complete-manifest stage and the exact leaf publications validated for it. Once installation begins, any failure leaves the marker and bytes for reconciliation rather than guessing at rollback.

func Prepare 

func Prepare(ctx context.Context, root string, manifest Manifest) (*Prepared, error)

Prepare performs the first descriptor-stable cold admission of every exact artifact and creates the complete-manifest stage. It hashes each leaf once.

func PrepareWithValidated 

func PrepareWithValidated(
	ctx context.Context,
	root string,
	manifest Manifest,
	validated map[string]*callerleaf.Publication,
) (*Prepared, error)

PrepareWithValidated reuses exact leaf publications already cold-opened by the caller worker. Missing or stale entries are opened once here.

func (*Prepared) Discard 

func (prepared *Prepared) Discard() error

func (*Prepared) Publish 

func (prepared *Prepared) Publish(
	ctx context.Context,
	commit func(context.Context, State) error,
) (*Publication, error)

Publish installs the marker and immutable manifest, commits the matching store pointer, then clears only that exact marker. Commit failure preserves the marker for runtime/startup recovery.

type Publication 

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

Publication is a descriptor-stable cold admission. Current performs only marker, directory, manifest, and leaf file-identity checks; it never opens or hashes leaf content.

func Open 

func Open(ctx context.Context, root string, expected State) (*Publication, error)

Open performs marker-free descriptor-stable cold validation of the exact complete state and every referenced leaf artifact.

func OpenMarked 

func OpenMarked(
	ctx context.Context,
	root, repository string,
) (*Publication, error)

OpenMarked derives the only admissible manifest name from a canonical marker inside repository's cryptographic directory, then performs matching-marker cold validation. The marker never selects another repository or path.

func OpenPublishing 

func OpenPublishing(ctx context.Context, root string, expected State) (*Publication, error)

OpenPublishing validates an exact manifest made durable before its store pointer commit. The matching marker is checked before and after all content.

func RecoverPublishing 

func RecoverPublishing(
	ctx context.Context,
	root, repository string,
	expectedExtractors []callerleaf.ExtractorIdentity,
	commit func(context.Context, State) error,
) (*Publication, error)

RecoverPublishing is the claimed-worker recovery seam. The caller holds its repository work lock; a successful callback is an exact store publish/no-op. Any callback failure preserves the marker and all bytes.

func (*Publication) ArtifactRefs 

func (publication *Publication) ArtifactRefs() []ArtifactRef

func (*Publication) Current 

func (publication *Publication) Current() bool

func (*Publication) CurrentResult 

func (publication *Publication) CurrentResult() (bool, error)

CurrentResult performs the same descriptor-stable identity fence as Current, but preserves operational filesystem failures for product-read boundaries. Missing or replaced derived authority is an ordinary transition and returns (false, nil); permission, device, and other path I/O failures remain errors.

func (*Publication) Manifest 

func (publication *Publication) Manifest() Manifest

func (*Publication) State 

func (publication *Publication) State() State

type ReconcileReport 

type ReconcileReport struct {
	StagesRemoved       int
	MarkersRecovered    int
	PublicationsCurrent int
	ReplacementsQueued  int
	PointersCleared     int
	OrphansObserved     int
}

func Reconcile 

func Reconcile(
	ctx context.Context,
	root string,
	state ReconcileStore,
	expected Expected,
	registry *Registry,
) (ReconcileReport, error)

Reconcile covers startup and may also be called under a higher-level worker serialization boundary. Unmarked pointerless bytes are never promoted.

type ReconcileStore 

type ReconcileStore interface {
	ListCallerPublicationRepositoriesPage(
		context.Context, string, int,
	) ([]string, error)
	CallerPublicationRepositoryEligible(context.Context, string) (bool, error)
	ListCallerPublications(context.Context) ([]State, error)
	CallerPublicationCurrent(context.Context, State) (bool, error)
	ClearCallerPublication(context.Context, string) error
	ForceCallerReplacement(context.Context, string) error
}

ReconcileStore is intentionally expressed in complete-publication types so this filesystem package does not import store and create a dependency cycle. The store or worker may provide a narrow adapter.

type RecordReference 

type RecordReference struct {
	PairIndex    int
	PairDigest   string
	ArtifactName string
	Record       callerleaf.RecordReference
}

RecordReference binds one leaf-local record reference to the exact pair and artifact that produced it. PairIndex is an implementation position rather than caller authority; the pair digest and artifact name are rechecked on every exact reread.

type Registry 

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

Registry owns process-local reader leases for complete immutable generations. Store revisions remain the visibility/result fence; this registry only prevents retired leaf bytes from being removed while a reader still holds them.

func NewRegistry 

func NewRegistry(root string) *Registry

func (*Registry) Acquire 

func (registry *Registry) Acquire(
	ctx context.Context,
	state State,
) (*Lease, error)

Acquire returns a reference-counted exact generation after its caller has rechecked that State against the store pointer. The current cached publication takes only identity checks. A cold miss is serialized per repository and may fill an empty slot or refresh the same logical state, but it never replaces a different current generation; only Observe may perform that store-authoritative transition.

func (*Registry) ActivateRepository 

func (registry *Registry) ActivateRepository(
	ctx context.Context,
	repository string,
) error

ActivateRepository cancels a durable leased-deletion tombstone before a same-name live repository starts installing new caller artifacts. Until its store-authoritative Observe arrives, final old-lease release preserves every basename because it does not yet have the successor's exact keep set.

func (*Registry) Close 

func (registry *Registry) Close() error

func (*Registry) Observe 

func (registry *Registry) Observe(
	ctx context.Context,
	publication *Publication,
) error

Observe installs one already cold-validated store-authoritative publication as the process current entry. A prior manifest is removed immediately; unshared prior leaf bytes are reclaimed only after its last lease releases.

func (*Registry) RemoveRepository 

func (registry *Registry) RemoveRepository(
	ctx context.Context,
	repository string,
) error

RemoveRepository retires process authority for a repository being deleted. Whole-directory removal is immediate without a lease. With a lease, an exact tombstone makes final-release removal crash-recoverable and lets a same-name replacement cancel deletion before writing new bytes.

func (*Registry) RetainedArtifactNames 

func (registry *Registry) RetainedArtifactNames(repository string) map[string]struct{}

RetainedArtifactNames returns a copy of every leaf basename protected by an active retired lease. It is the bounded keep set for reconciliation cleanup.

func (*Registry) Retire 

func (registry *Registry) Retire(
	ctx context.Context,
	repository string,
) error

Retire removes current visibility from the process cache. Its immutable manifest is not needed by an existing lease, which holds parsed state; leaf bytes remain until the last reference releases.

type State 

type State struct {
	Schema         string                        `json:"schema"`
	Generation     callerleaf.GenerationIdentity `json:"generation"`
	PairSetDigest  string                        `json:"pair_set_digest"`
	Aggregate      callerleaf.AggregateReceipt   `json:"aggregate"`
	ManifestDigest string                        `json:"manifest_digest"`
	Manifest       string                        `json:"manifest"`
}

State is the primitive store-pointer projection of a complete filesystem publication. It carries the full semantic generation rather than relying on a mutable control row to reconstruct visibility after the fact.

func ParseRetentionManifest 

func ParseRetentionManifest(raw []byte) (State, int64, error)

ParseRetentionManifest validates canonical manifest metadata without opening or hashing a leaf payload.

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.