Help us shape the future of Go! Take the 2026 Go Developer Survey

versionstore

package
v0.136.0 Latest Latest
Warning

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

Go to latest
Published: Oct 28, 2026 License: MIT Imports: 49 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrForbidden is what the viewer sees but may not do.
	ErrForbidden = errors.New("versions: forbidden")
)
View Source
var (
	// ErrInvalid is a malformed request.
	ErrInvalid = errors.New("versions: invalid")
)
View Source
var (
	// ErrNoDownload is a version without the file its kind's download
	// serves: nothing uploaded, or an upload that failed or was dropped.
	ErrNoDownload = errors.New("versions: no download")
)
View Source
var (
	// ErrNotFound is a content or version that does not exist, or that the
	// viewer may not see.
	ErrNotFound = errors.New("versions: not found")
)
View Source
var (
	// ErrNotReady is a version whose media is still processing or not yet published.
	ErrNotReady = errors.New("versions: media not ready")
)

Functions

func ChapterPathHooks

func ChapterPathHooks(pool *pgxpool.Pool, schema string, registry *mediastore.Registry, wake func(context.Context, pgx.Tx, contentref.ContentRef) error) mediastore.Hooks

ChapterPathHooks installs the same marker contract in stock worker recovery. The journal must not settle a recovered rename without its catalog update.

func EntityOwner

func EntityOwner(kind, id string) string

EntityOwner is the quota owner of an entity's uploads: "{kind}:{id}".

func LockSource

func LockSource(ctx context.Context, pool *pgxpool.Pool, tenant, version string) (func(), error)

LockSource serializes source selection with catalog segment writes. Acquire it before a SQL transaction/row lock; manifest commits may notify the catalog.

func LockSources

func LockSources(ctx context.Context, pool *pgxpool.Pool, tenant string, vers []string) (func(), error)

LockSources serializes source selection and catalog segment writes before either takes row locks. A batch uses one dedicated connection, leaving the caller's pool available for manifest commits and catalog notifications.

func ParseEntityOwner

func ParseEntityOwner(owner string) (kind, id string, ok bool)

ParseEntityOwner is EntityOwner's kind and id; ok is false for any other owner.

func PrepareDerivatives

func PrepareDerivatives(pool *pgxpool.Pool, schema string, manifests *mediastore.Manifests, uploads *mediastore.Uploads) func(context.Context, contentref.ContentRef) error

PrepareDerivatives prepares page order and automatic cover inputs inside the existing derivative attempt. Drafts get the same preparation without publishing.

func ProcessingPublisher

func ProcessingPublisher(pool *pgxpool.Pool, riverSchema, contentSchema string, registry *mediastore.Registry) (func(context.Context, pgx.Tx, contentref.ContentRef) error, error)

ProcessingPublisher wakes the accepted release from a processor's completion transaction, including stock external workers. It preserves an unreleased edition's requested date and a follow-up when an older snapshot job is running.

func QueueFor

func QueueFor(catalog string) string

QueueFor is the edition-worker queue for one immutable catalog key. The media tenant/app path partition is not necessarily this catalog key.

func RetirementBarrier

func RetirementBarrier(pool *pgxpool.Pool, schema string, registry *mediastore.Registry) func(context.Context, contentref.ContentRef, *mediastore.Manifest) error

RetirementBarrier supplies the catalog-side media barrier to standalone workers. It shares the exact withdrawal logic used by embedded writers; workers need no authentication or application callbacks to retire a file.

Types

type Archive

type Archive struct {
	Name string // the attachment's file name
	Type string // application/zip, or the configured single file's content type
	Size int64  // single-file size; ZIPs stream without a known size
	// contains filtered or unexported fields
}

Archive is an authorized ZIP or exact configured single-file transfer.

func (*Archive) WriteTo

func (a *Archive) WriteTo(w io.Writer) (int64, error)

WriteTo streams the archive within its request's context.

type Facets

type Facets interface {
	RefreshTx(ctx context.Context, tx pgx.Tx, vers []string) error
}

Facets refreshes the listing projection of versions whose derived media facts changed, in the writing transaction.

type Media

type Media struct {
	Manifests *mediastore.Manifests
	Uploads   *mediastore.Uploads
	Jobs      *mediastore.Jobs
	Reader    *mediastore.Reader // signs file downloads; nil serves none
}

Media is the media runtime built over Service.Hooks.

type Options

type Options struct {
	Tenant string // the content tables' tenant
	Schema string // ContentKit's schema
	Pool   *pgxpool.Pool
	Kinds  kinds.Config       // the site's content and entity kinds
	Auth   auth.Authenticator // the host's: staff and group scope checks
	// MediaConfigured requires Bind before a release can run. A service without
	// media still owns publication requests, completed access and deadlines.
	MediaConfigured bool
	// AccountExists verifies avatar targets in this tenant's account directory.
	// Scoped engines install it; nil preserves the legacy host contract.
	AccountExists func(context.Context, string) (bool, error)
	// Resolver decides versions ({kind, content, version}) for a viewer:
	// Visible (live, or edited by them), Accessible (opened by them) and
	// Editor.
	Resolver resolve.Resolver
	// Gate answers the tiers a viewer holds for download quotas; optional.
	Gate      *entitlement.Gate
	Facets    Facets
	Others    Others                  // nil refuses every other kind
	Policy    versions.DownloadPolicy // the host's download policy; nil allows every download and marks none
	Downloads versions.Downloads
	// Redis shares download counts across replicas; nil keeps them per process.
	Redis  redis.UniversalClient
	Logger *slog.Logger
	Now    func() time.Time
}

Options configure a Service.

type Others

type Others interface {
	resolve.Resolver
	media.UploadAuthorizer
}

Others answer the media kinds of neither contents nor groups: posts' and polls' images.

type Service

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

Service owns publication for content versions and their optional media.

func New

func New(o Options) (*Service, error)

New validates o. When media is configured, build it with Hooks, then Bind it.

func (*Service) Archive

func (s *Service) Archive(ctx context.Context, request versions.ArchiveRequest) (*Archive, error)

Archive opens the ZIP or single file a Download granted. The ticket binds its viewer, marks, name and exact ordered source revision. Access, publication, chapter release and policy are checked again, even when its ZIP is already cached.

func (*Service) Bind

func (s *Service) Bind(m Media) error

Bind attaches the media runtime built over Hooks.

func (*Service) CheckRestorableTx

func (s *Service) CheckRestorableTx(ctx context.Context, tx pgx.Tx, targets []versions.Target) error

CheckRestorableTx refuses a version after its permanent erasure claim, including a claim whose storage response or catalog transaction failed. Callers hold the same parent/version locks as DeleteTx.

func (*Service) Covers

func (s *Service) Covers(ctx context.Context, covers []versions.CoverOf) ([][]media.PublicRendition, error)

Covers resolves covers to their public renditions, per cover in order, in two queries for the page. A content's cover is the image its version's cover selects, else the version's first cover image, else its kind's default.

func (*Service) Delete

func (s *Service) Delete(ctx context.Context, targets []versions.Target) error

Delete erases the already-fenced exact versions. A stable operation ID preserves the original cleanup targets when a purge retries after failure.

func (*Service) DeleteTx

func (s *Service) DeleteTx(ctx context.Context, tx pgx.Tx, targets []versions.Target) error

DeleteTx permanently fences targets while their catalog rows are locked. The caller commits this claim before Delete erases storage, so retirement hooks never wait on catalog locks held by the erasing transaction.

func (*Service) DismissPageNotice

func (s *Service) DismissPageNotice(ctx context.Context, actor access.Actor, t versions.Target, id string) error

DismissPageNotice hides a current notice; dismissing again is a no-op.

func (*Service) Download

func (s *Service) Download(ctx context.Context, actor access.Actor, t versions.Target) (*versions.FileDownload, error)

Download grants t's download to actor, what its kind's download serves (kinds.Kind.Download), as the host's policy allows, and charges it to actor's quota. Page archives include only the released, authorized prefix; other files require whole-version access. ErrNotFound when the kind serves none, an UnavailableError when the policy refuses, ErrNoDownload when the version has nothing to serve, ErrNotReady while it is placed or produced, a QuotaError past the quota.

func (*Service) EntityCovers

func (s *Service) EntityCovers() entities.CoverResolver

EntityCovers is Covers for the entities API's cards and pages (entities.Options.Covers).

func (*Service) EntityFolders

func (s *Service) EntityFolders() entitystore.Folders

EntityFolders hides, shows and deletes entities' media folders for the entities API (entities.Options.Folders).

func (*Service) Handler

func (s *Service) Handler(a auth.Authenticator, log *slog.Logger) (http.Handler, error)

Handler serves the versions module's routes, each behind its tier's gate.

func (*Service) Hooks

func (s *Service) Hooks() mediastore.Hooks

Hooks are media's hooks over the content model, for media.NewRegistry.

func (*Service) Ladder

func (s *Service) Ladder(kind string) string

Ladder is the folder of the kind's first HLS ladder (a read's hls entry), "" when it streams none or one per upload.

func (*Service) PageNotices

func (s *Service) PageNotices(ctx context.Context, actor access.Actor, t versions.Target) (versions.PageNotices, error)

PageNotices returns a version's undismissed notices to its editors only.

func (*Service) Plan

Plan derives chapter spans from current metadata over an immutable file snapshot. Every span reads the same canonical version item.

func (*Service) RestorePageNotice

func (s *Service) RestorePageNotice(ctx context.Context, actor access.Actor, t versions.Target, id string) (versions.PageNotices, error)

RestorePageNotice puts a removed notice's pages back where they were (an excluded source keeps its place) and clears the notice.

func (*Service) ResumeDeletes

func (s *Service) ResumeDeletes(ctx context.Context, limit int) (int, error)

ResumeDeletes keeps late-write cleanup in the content purge operation.

func (*Service) RiverJobs

func (s *Service) RiverJobs() riverhelpers.Contribution

RiverJobs contributes the publication worker and queue to the host's River composition, beside media's own.

func (*Service) SchedulePublicationTx

func (s *Service) SchedulePublicationTx(ctx context.Context, tx pgx.Tx, targets []versions.Target) error

SchedulePublicationTx accepts current catalog/manifest intent in the same transaction as its runnable River obligation. Empty Version expands to the gallery's editions; each remains an independent request and access boundary.

func (*Service) SetReaderMeta

func (s *Service) SetReaderMeta(ctx context.Context, actor access.Actor, t versions.Target, rm versions.ReaderMeta) error

SetReaderMeta stores v's reader metadata for an editor: every page, anchor and file it names must exist.

func (*Service) SyncFences

func (s *Service) SyncFences(ctx context.Context, targets []versions.Target) error

SyncFences makes each target version's gateway fence follow the catalog: a version deleted itself or with its content serves nothing until restored. Each content's rows stay share-locked through the storage calls, so a deletion, restore or erasure claim commits before or after a sync, never during one. Catalog writes sync after they commit; the publication job the same write scheduled syncs again, so a crash cannot leave the fence stale.

func (*Service) ValidateChapterStartsTx

func (s *Service) ValidateChapterStartsTx(ctx context.Context, tx pgx.Tx, target versions.Target, starts []string) error

ValidateChapterStartsTx checks authored starts against the current source manifest, including drafts whose renditions have not finished. The catalog caller holds the version's source lock before taking its row locks.

func (*Service) WithChapterLocks

func (s *Service) WithChapterLocks(ctx context.Context, targets []versions.Target, fn func() error) error

WithChapterLocks settles admitted media changes before catalog marker authoring. The caller holds source locks first and takes catalog rows inside fn; uploads/recovery take manifest then catalog locks in the same order.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL