media

type Animation string

type Aspect struct{ W, H int }

type AudioTrack struct {
	ID        string    `json:"id"`
	Lang      string    `json:"lang,omitempty"`
	Label     string    `json:"label,omitempty"`
	Default   bool      `json:"default,omitempty"`
	Bandwidth int       `json:"bandwidth,omitempty"`
	Codecs    string    `json:"codecs,omitempty"`
	Blob      string    `json:"blob"`
	Segments  []Segment `json:"segments"`
}

type Capabilities struct {
	ConditionalPut bool // If-Match / If-None-Match on PUT
	ChecksumSHA256 bool // x-amz-checksum-sha256 enforced on PUT
}

type CommitBody struct {
	Ref RefBody `json:"ref"`
	Ops []Op    `json:"ops"`
}

type CommitFile struct {
	Name       string         `json:"name"`
	Original   string         `json:"original"`
	Type       string         `json:"type,omitempty"`
	Size       int64          `json:"size,omitempty"`
	Edit       *Edit          `json:"edit,omitempty"`
	Meta       map[string]any `json:"meta,omitempty"`
	Unattached bool           `json:"unattached,omitempty"`
}

type CommitReply struct {
	Files []CommitFile `json:"files"`
}

type CompleteReply struct {
	Name string `json:"name"`
	Type string `json:"type"`
	Size int64  `json:"size"`
}

type CopyOptions struct {
	IfMatch string
}

type Crop struct {
	X int `json:"x"`
	Y int `json:"y"`
	W int `json:"w"`
	H int `json:"h"`
}

type Deletion struct {
	Ref   contentref.ContentRef
	Owner string
}

type Delivery struct {
	Mode DeliveryMode
	// BaseURL is the access worker origin for this site, e.g.
	// "https://media.doujins.com".
	BaseURL string
	// CookieDomain is the site's registrable domain, e.g. "doujins.com";
	// required in cookie mode, because a host-only cookie never reaches media.
	CookieDomain string
	// SigningKey is the current key of the ring the access worker verifies.
	SigningKey token.Key
	// TTL is the minimum token lifetime (default 1h); expiries round up to
	// Window (default token.DefaultWindow).
	TTL    time.Duration
	Window time.Duration
}

type DeliveryMode string

type Dims struct {
	W int `json:"w"`
	H int `json:"h"`
}

type Download struct {
	Blob   string `json:"blob"`
	Type   string `json:"type,omitempty"`
	Size   int64  `json:"size,omitempty"`
	Spec   string `json:"spec,omitempty"`
	Inputs string `json:"inputs,omitempty"` // hash of the ordered input blobs
}

type DownloadInfo struct {
	Key  string `json:"key"`
	Name string `json:"name"`
	Type string `json:"type,omitempty"`
	Size int64  `json:"size,omitempty"`
	URL  string `json:"url"`
}

type Edit struct {
	Crop   *Crop `json:"crop,omitempty"`
	Rotate int   `json:"rotate,omitempty"` // clockwise degrees: 0, 90, 180 or 270
}

type EncodeProgress struct {
	Phase         string  `json:"phase"`
	QueuePosition int     `json:"queue_position,omitempty"` // 1 = next; 0 = unknown or behind a file of the same job
	SegmentsDone  int     `json:"segments_done,omitempty"`
	SegmentsTotal int     `json:"segments_total,omitempty"`
	Percent       float64 `json:"percent"`
	Speed         float64 `json:"speed,omitempty"`
	ETA           float64 `json:"eta,omitempty"`
	At            int64   `json:"at"` // unix milliseconds of the measurement
	Stalled       bool    `json:"stalled,omitempty"`
	// Stage of Stages: a file with rungs above 1080 plays after stage 1 while
	// stage 2 encodes them.
	Stage  int `json:"stage,omitempty"`
	Stages int `json:"stages,omitempty"`
}

type EncodeStatus struct {
	Files  map[string]EncodeProgress
	Queued *EncodeProgress
	Item   *EncodeProgress
}

type ErrorDetails struct {
	Width      int      `json:"width,omitempty"`       // image_too_small: the edited width; image_too_large: the source's
	Height     int      `json:"height,omitempty"`      // image_too_large: the source's
	MinWidth   int      `json:"min_width,omitempty"`   // image_too_small
	MaxPixels  int      `json:"max_pixels,omitempty"`  // image_too_large
	Type       string   `json:"type,omitempty"`        // the declared type (image_unreadable, type_not_allowed, too_large)
	Allowed    []string `json:"allowed,omitempty"`     // type_not_allowed: the kind's types
	Size       int64    `json:"size,omitempty"`        // too_large: bytes
	MaxBytes   int64    `json:"max_bytes,omitempty"`   // too_large
	Frames     int      `json:"frames,omitempty"`      // animation_too_long, image_too_large: the animation's
	MaxFrames  int      `json:"max_frames,omitempty"`  // animation_too_long
	Seconds    float64  `json:"seconds,omitempty"`     // animation_too_long: running time
	MaxSeconds float64  `json:"max_seconds,omitempty"` // animation_too_long
}

type ErrorReply struct {
	Error      string        `json:"error"`
	Code       string        `json:"code"`
	RetryAfter int           `json:"retry_after,omitempty"` // seconds, with 429
	Originals  []string      `json:"originals,omitempty"`   // not_uploaded at commit: the originals to upload again
	Details    *ErrorDetails `json:"details,omitempty"`     // image refusals
}

type Exposure struct {
	Poster bool `json:"poster"`
}

type ExposurePolicy func(ctx context.Context, ref contentref.ContentRef, anonymous access.Resolution) Exposure

type File struct {
	Name     string             `json:"name"`
	Original string             `json:"original"`
	Master   string             `json:"master,omitempty"`
	Type     string             `json:"type,omitempty"`
	Size     int64              `json:"size,omitempty"`
	Edit     *Edit              `json:"edit,omitempty"`
	Dims     *Dims              `json:"dims,omitempty"`
	Meta     map[string]any     `json:"meta,omitempty"`
	Variants map[string]Variant `json:"variants,omitempty"`
	HLS      *HLS               `json:"hls,omitempty"`
	// Failure is why the image processor cannot derive this source through
	// this edit (Of); a new source or edit clears it.
	Failure *FileFailure `json:"failure,omitempty"`
	// Unattached marks a file processed on upload (UploadOptions.ProcessOnUpload)
	// that is not part of the item yet: reads leave it out (editors may ask
	// for it) until an attach op. Removing it discards its objects at once.
	Unattached bool `json:"unattached,omitempty"`
}

type FileFailure struct {
	Of      string        `json:"of"`             // File.FailureKey it was recorded for
	Message string        `json:"message"`        // what went wrong, or the rule an ImageError states
	Code    string        `json:"code,omitempty"` // an ImageError's code
	Details *ErrorDetails `json:"details,omitempty"`
}

type FileInfo struct {
	Index    int     `json:"index"`
	Name     string  `json:"name,omitempty"`
	Type     string  `json:"type,omitempty"`
	Width    int     `json:"w,omitempty"`
	Height   int     `json:"h,omitempty"`
	Duration float64 `json:"duration,omitempty"`
	Edit     *Edit   `json:"edit,omitempty"` // editors only: with Dims, what re-cropping needs
	Dims     *Dims   `json:"dims,omitempty"` // editors only: the source's size; w/h is the edited size
	Teaser   bool    `json:"teaser,omitempty"`
	Locked   bool    `json:"locked,omitempty"`
	HLS      bool    `json:"hls,omitempty"`
	// Unattached is an editor's file processed on upload, not yet attached
	// (ReadOptions.Unattached).
	Unattached bool   `json:"unattached,omitempty"`
	Failed     string `json:"failed,omitempty"` // editors only: why the file cannot be processed (video encode, image derive)
	// FailedCode and FailedDetails type an image refusal (image_too_large,
	// animation_not_allowed, …); editors only.
	FailedCode    string        `json:"failed_code,omitempty"`
	FailedDetails *ErrorDetails `json:"failed_details,omitempty"`
	// Progress of a pending encode (none yet, or a replaced source); served
	// with the file, as it reveals only timing and queue depth.
	Progress *EncodeProgress `json:"progress,omitempty"`
	Variant  string          `json:"variant,omitempty"`
	URL      string          `json:"url,omitempty"`
}

type FilesBody struct {
	Ref   RefBody  `json:"ref"`
	Names []string `json:"names,omitempty"`
}

type FilesReply struct {
	Files []FileInfo `json:"files"`
}

type Fit string

type FolderNotEmptyError struct {
	Prefix string
	Keys   []string
}

type FrameGrabber interface {
	Frame(ctx context.Context, item Item, f File, t float64, width int) ([]byte, error)
}

type GetOptions struct {
	IfNoneMatch string
	Range       string
}

type Grant struct {
	Item       Item
	Resolution access.Resolution
	Manifest   *Manifest
	Expires    time.Time
	// contains filtered or unexported fields
}

type HLS struct {
	Source string       `json:"source"`
	Spec   string       `json:"spec,omitempty"`
	Error  string       `json:"error,omitempty"`
	Video  []Rendition  `json:"video,omitempty"`
	Audio  []AudioTrack `json:"audio,omitempty"`
	Subs   []Subtitle   `json:"subs,omitempty"`
	Sprite *Sprite      `json:"sprite,omitempty"`
	// Pending lists the rungs of a later encode stage: the file plays at the
	// rungs in Video until they are added.
	Pending []int `json:"pending,omitempty"`
}

type HandlerOptions struct {
	Tenant   string
	Identity Identity
	Logger   *slog.Logger
	// Limit is the per-viewer rate limit (default ViewerLimit{}: 2/s, burst
	// 120, per process; set Limit.Redis to share it across replicas).
	// Viewers are keyed by tenant and Actor.ID, anonymous ones by Actor.IP,
	// else by the connection's address: behind a proxy, set Actor.IP from
	// the client address the proxy forwards.
	Limit ViewerLimit
}

type Hooks struct {
	// DownloadName returns the display name a download is saved under, e.g.
	// "[Artist] Title (English).zip". Default: "{content_id}-{key}{ext}".
	DownloadName func(ctx context.Context, ref contentref.ContentRef, key string, d Download) (string, error)
	// Failed reports a file a processor cannot derive (an undecodable image,
	// say); file is the manifest file name, or the slot name. The job does not
	// retry it; a new commit does.
	Failed func(ctx context.Context, ref contentref.ContentRef, file string, err error)
	// SlotEncoded reports that a slot's outputs are written, with their
	// aspect (for native slots, whose shape follows the image): hosts record
	// it to list the slot with Reader.ListedSlot without reads.
	SlotEncoded func(ctx context.Context, ref contentref.ContentRef, slot string, aspect Aspect)
}

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

type Identity interface {
	Actor(ctx context.Context) (access.Actor, bool)
}

type ImageError struct {
	Code    string
	Message string
	Details ErrorDetails
}

type IngestRequest struct {
	Ref  contentref.ContentRef
	Name string
	Type string
	Body io.Reader // read once, sequentially
	Size int64     // expected size, checked when > 0; required when the actor is rate- or quota-limited
	Op   string    // OpInsert (default) or OpReplace
	Meta map[string]any

	// Resume continues a multipart upload a previous Ingest left behind:
	// parts already stored with the same bytes are not uploaded again (the
	// body is still read and hashed). An unknown upload starts afresh.
	Resume *IngestUpload
	// OnUpload receives the multipart upload once created, for the host to
	// persist for Resume. With it set a failed Ingest keeps the upload (the
	// bucket's abort-incomplete rule removes it after a day); without it the
	// upload is aborted.
	OnUpload func(IngestUpload) error

	PartSize    int64 // default IngestPartSize; at least 5 MiB
	Concurrency int   // parallel part uploads; default IngestConcurrency
}

type IngestResult struct {
	Original string
	Size     int64
	SHA256   []byte // of the whole file
	Manifest *Manifest
}

type IngestUpload struct {
	Original string `json:"original"` // u-{uuid}
	UploadID string `json:"upload_id"`
}

type InsertFunc func(ctx context.Context, args river.JobArgs, o *river.InsertOpts) (*rivertype.JobInsertResult, error)

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

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

type JobsConfig struct {
	Store Store
	Kinds *Registry
	// Tenants are the folders the periodic sweep pass covers; folders of
	// kinds missing from Kinds are skipped.
	Tenants []string
	// Grace protects in-flight uploads, jobs and mid-stream viewers: a folder
	// is swept only when its manifests are this old, and only objects this old
	// are deleted. Default 24 h.
	Grace time.Duration
	// SweepInterval is the periodic pass interval. Default 24 h.
	SweepInterval time.Duration
	// LateUploadWindow delays the second pass of a folder deletion, which
	// removes PUTs and multipart completions that land after the first. It
	// must exceed the longest upload presign TTL and the 1-day multipart
	// abort rule. Default 25 h.
	LateUploadWindow time.Duration
	Limiter          UploadLimiter // releases a deleted item's quota; optional
	// Resolver decides, with an anonymous actor, what of a video item is
	// public (Publish); without it no poster is published.
	Resolver access.ContentResolver
	// Exposure maps that anonymous resolution to what is published; default
	// DefaultExposure (drafts nothing, free items all, others the poster).
	Exposure   ExposurePolicy
	Queue      string // default "contentkit_media"
	MaxWorkers int    // default 2
	Logger     *slog.Logger
	Now        func() time.Time // clock for grace decisions; default time.Now
}

type Kind struct {
	Name      string
	Versioned bool // manifests live at manifests/{version_id}.json
	// Types are the accepted content types (empty: any); image processing
	// also requires the bytes to be the declared format.
	Types    []string
	MaxBytes int64
	// MaxFiles caps a manifest's files; 0 is unlimited.
	MaxFiles int
	// TypeLimits are caps per top-level type ("image", "video"): a set
	// MaxBytes replaces the kind's for that type, and MaxFiles caps that
	// type's files. A kind may mix images (Specs) and videos (Video).
	TypeLimits map[string]Limit
	Specs      map[string]Spec // variant name → spec
	Slots      map[string]Slot // public slot name → outputs
	// Inline enables inline images: write-once public images with random ids
	// ("i-{uuid}", from NewInlineName), each re-encoded with this spec from
	// originals/{id} to public/{id}.webp. Post bodies and poll options use them.
	Inline *Spec
	// Animation is the policy for animated images (GIF, WebP) in files and
	// inline images; slots set their own.
	Animation Animation
	Video     *Video // nil: no video encoding
	// Zip names the variant packed, in file order, into downloads["zip"];
	// "" offers no zip.
	Zip string
}

type Limit struct {
	MaxBytes int64
	MaxFiles int
}

type Locker interface {
	Lock(ctx context.Context, key string) (unlock func(), err error)
}

type Manifest struct {
	Files     []File              `json:"files"`
	Meta      map[string]any      `json:"meta,omitempty"`
	Downloads map[string]Download `json:"downloads,omitempty"`
}

type ManifestOptions struct {
	// Locker is required when the store lacks ConditionalPut; edits then run
	// under it and write unconditionally. See PGLocker.
	Locker     Locker
	CacheSize  int // manifests kept in process, revalidated by ETag; default 4096
	MaxRetries int // CAS attempts per edit; default 16
	// Sweeps, when set, schedules the folder's sweep after every written
	// edit: the host's *Jobs, or in the media worker a *HostQueue. Scheduling
	// is best-effort (logged); the periodic sweep pass backs it up.
	Sweeps SweepScheduler
}

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

type MasterOptions struct {
	Audio, Subs []string
}

type Multipart struct {
	Ticket      string
	MinPartSize int64
	MaxPartSize int64
	MaxParts    int
}

type MultipartReply struct {
	Ticket      string `json:"ticket"`
	MinPartSize int64  `json:"min_part_size"`
	MaxPartSize int64  `json:"max_part_size"`
	MaxParts    int    `json:"max_parts"`
}

type Object struct {
	Key            string
	Size           int64
	ETag           string
	ContentType    string
	CacheControl   string
	ContentRange   string
	LastModified   time.Time
	ChecksumSHA256 []byte            // set when the backend stored a full-object SHA-256
	Metadata       map[string]string // user metadata (x-amz-meta-*), lower-case keys; Head and Get
}

type Op struct {
	Op       string         `json:"op"`
	Name     string         `json:"name"`
	Original string         `json:"original,omitempty"`
	Index    *int           `json:"index,omitempty"`
	To       string         `json:"to,omitempty"`
	Meta     map[string]any `json:"meta,omitempty"` // insert, replace: the file's meta; attach: merged into it
	Edit     *Edit          `json:"edit,omitempty"` // edit, insert, replace: the image's edit (replace drops the old one)
	// Unattached inserts the file processed but not yet part of the item
	// (UploadOptions.ProcessOnUpload); attach makes it one, remove discards it.
	Unattached bool `json:"unattached,omitempty"`
}

type OrphanFolder struct {
	Prefix  string
	ID      string
	ValidID bool
	Objects int
	Newest  time.Time
	Deleted bool
}

type OrphanReport struct {
	Folders int
	Orphans []OrphanFolder
}

type OrphanSweep struct {
	Tenant, Kind string
	// Exists reports which of ids the host still has (a batch of at most
	// 500). An id it omits is an orphan.
	Exists func(ctx context.Context, ids []string) (map[string]bool, error)
	// Grace skips folders with an object newer than this (default the Jobs
	// grace), so an item created meanwhile is never taken for an orphan.
	Grace time.Duration
	// Delete removes orphans; otherwise they are only reported.
	Delete bool
}

type OutputURLs struct {
	BaseURL     string   // the access worker origin
	EditorToken string   // the item's editor/ folder token; editors only
	Exposure    Exposure // what the item has published
}

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

type PGLimits struct {
	FilesPerHour int
	BytesPerDay  int64
	// Quota is the owner's storage cap in bytes (<= 0 unlimited); nil disables quotas.
	Quota func(ctx context.Context, tenant, owner string) (int64, error)
	// ReservationTTL drops unsettled reservations (commit still enforces the
	// quota); default 24h.
	ReservationTTL time.Duration
}

type Part struct {
	Number int32
	Size   int64
	ETag   string
	SHA256 []byte
}

type PartBody struct {
	Number int32  `json:"number"`
	Size   int64  `json:"size"`
	SHA256 string `json:"sha256"`
}

type PartReply struct {
	Number  int32         `json:"number"`
	Size    int64         `json:"size,omitempty"`
	SHA256  string        `json:"sha256,omitempty"`
	Request *RequestReply `json:"request,omitempty"`
}

type PartRequest struct {
	Number int32
	Size   int64
	SHA256 []byte
}

type PartsBody struct {
	Ticket string     `json:"ticket"`
	Parts  []PartBody `json:"parts"`
}

type PartsReply struct {
	Parts []PartReply `json:"parts"`
}

type PosterFrame struct {
	Version string  `json:"version,omitempty"` // manifest holding File, for versioned kinds
	File    string  `json:"file"`
	Time    float64 `json:"time"`
	Auto    bool    `json:"auto,omitempty"`   // chosen by the worker (first non-flat frame)
	Source  string  `json:"source,omitempty"` // original grabbed from; "" until grabbed
}

type PosterManifest struct {
	SlotManifest
	File      string           `json:"file,omitempty"`
	Time      *float64         `json:"time,omitempty"`
	Selection *PosterSelection `json:"selection,omitempty"`
}

type PosterRequest struct {
	Source string
	File   string // default: the first video file
	Time   float64
	SHA256 []byte
	Edit   *Edit
}

type PosterSelection struct {
	Source  string   `json:"source"`
	Version string   `json:"version,omitempty"`
	File    string   `json:"file,omitempty"`
	Time    *float64 `json:"time,omitempty"`
}

type PresignBody struct {
	Ref    RefBody `json:"ref"`
	Type   string  `json:"type"`
	Size   int64   `json:"size"`
	SHA256 string  `json:"sha256,omitempty"` // required up to 64 MiB, for slots and inline images
	Slot   string  `json:"slot,omitempty"`
	Inline bool    `json:"inline,omitempty"` // a new inline image; the reply names it
}

type PresignPut struct {
	ContentType string
	Size        int64
	SHA256      []byte
	TTL         time.Duration
}

type PresignReply struct {
	Name            string          `json:"name"`
	Exists          bool            `json:"exists,omitempty"`
	Put             *RequestReply   `json:"put,omitempty"`
	Multipart       *MultipartReply `json:"multipart,omitempty"`
	ProcessOnUpload bool            `json:"process_on_upload,omitempty"`
}

type PresignRequest struct {
	Ref    contentref.ContentRef
	Type   string
	Size   int64
	SHA256 []byte
	Slot   string
	Inline bool
}

type Presigned struct {
	Name            string
	Exists          bool
	Put             *PresignedRequest
	Multipart       *Multipart
	ProcessOnUpload bool
}

type PresignedPart struct {
	Number int32
	PresignedRequest
}

type PresignedRequest struct {
	Method  string
	URL     string
	Header  http.Header
	Expires time.Time
}

type ProcessCanceler interface {
	Cancel(ctx context.Context, ref contentref.ContentRef) (int, error)
}

type ProcessJob struct {
	Ref  contentref.ContentRef
	Slot string
}

type ProcessQueue interface {
	Enqueue(ctx context.Context, job ProcessJob) error
}

type ProgressSource interface {
	EncodeProgress(ctx context.Context, ref contentref.ContentRef) (EncodeStatus, error)
}

type PutOptions struct {
	ContentType    string
	CacheControl   string
	ChecksumSHA256 []byte
	IfMatch        string
	IfNoneMatch    string
	Metadata       map[string]string
}

type ReadOptions struct {
	// Variants in preference order: each file in range gets a URL for the
	// first one it has (EditorOnly ones only for editors). Empty returns
	// metadata only.
	Variants      []string
	Offset, Limit int
	// Unattached also lists an editor's unattached files (FileInfo.Unattached).
	Unattached bool
}

type ReadResult struct {
	Access       string         `json:"access"`
	Total        int            `json:"total"`
	PreviewLimit int            `json:"preview_limit"`
	Offset       int            `json:"offset"`
	Limit        int            `json:"limit"`
	Expires      int64          `json:"expires"` // unix seconds; URLs and cookie stop working then
	Meta         map[string]any `json:"meta,omitempty"`
	Files        []FileInfo     `json:"files"`
	Downloads    []DownloadInfo `json:"downloads,omitempty"`
	// Cookie must be set on the response (cookie mode, full access).
	Cookie *http.Cookie `json:"-"`
}

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

type ReaderOptions struct {
	Manifests *Manifests
	Kinds     *Registry
	Resolver  access.ContentResolver
	Delivery  Delivery
	Hooks     Hooks
	// Progress adds live encode progress to pending video files; optional.
	Progress ProgressSource
	// MaxLimit caps ReadOptions.Limit (default 200); DefaultLimit is used when
	// Limit is 0 (default 50).
	MaxLimit, DefaultLimit int
	Now                    func() time.Time
}

type RefBody struct {
	Kind    string `json:"kind"`
	ID      string `json:"id"`
	Version string `json:"version,omitempty"`
}

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

type Rendition struct {
	Rung      int       `json:"rung"`
	Width     int       `json:"w"`
	Height    int       `json:"h"`
	Bandwidth int       `json:"bandwidth"`
	Average   int       `json:"avg,omitempty"`
	Codecs    string    `json:"codecs"`
	Blob      string    `json:"blob"`
	Segments  []Segment `json:"segments"`
}

type RequestReply struct {
	Method  string            `json:"method"`
	URL     string            `json:"url"`
	Headers map[string]string `json:"headers"`
	Expires time.Time         `json:"expires"`
}

type RerunArgs interface {
	river.JobArgs
	FollowUp(id int64) river.JobArgs
}

type Reservation struct {
	Tenant   string
	Uploader string
	Owner    string
	Key      string
	Size     int64
}

type Segment struct {
	Offset  int64
	Length  int64
	Seconds float64
}

type Settlement struct {
	Tenant  string
	Owner   string
	Keys    []string
	Delta   int64
	Enforce bool
}

type Slot struct {
	Aspect    Aspect
	Widths    []int
	MinWidth  int
	Quality   int // WebP quality; default 80
	Animation Animation
}

type SlotBody struct {
	Ref    RefBody `json:"ref"`
	Slot   string  `json:"slot"`
	SHA256 string  `json:"sha256"`
	Edit   *Edit   `json:"edit,omitempty"`
}

type SlotEditBody struct {
	Ref  RefBody `json:"ref"`
	Slot string  `json:"slot"`
	Edit *Edit   `json:"edit,omitempty"`
}

type SlotFromFile struct {
	Ref  contentref.ContentRef // the slot's item; a version ref also names From's manifest
	Slot string
	// From is the manifest holding File when it is not Ref's: another item
	// (or version) of the same tenant, e.g. a post image for a channel avatar.
	From contentref.ContentRef
	File string
	// Edit crops the copy (default: the file's own edit; an empty Edit clears it).
	Edit *Edit
}

type SlotFromFileBody struct {
	Ref  RefBody  `json:"ref"`
	Slot string   `json:"slot"`
	From *RefBody `json:"from,omitempty"`
	File string   `json:"file"`
	Edit *Edit    `json:"edit,omitempty"`
}

type SlotImage struct {
	Name string `json:"name"`
	W    int    `json:"w"`
	H    int    `json:"h"`
	URL  string `json:"url"`
}

type SlotManifest struct {
	Aspect  Aspect      `json:"aspect"`         // "W:H"; a native slot's from its outputs ("" before any)
	Edit    *Edit       `json:"edit,omitempty"` // nil: the centred crop at aspect (native: the whole image)
	Dims    *Dims       `json:"dims,omitempty"` // the committed original, EXIF-oriented, once measured
	Outputs []SlotImage `json:"outputs"`
	Pending bool        `json:"pending"`         // a commit, edit or spec change is not encoded yet
	Error   string      `json:"error,omitempty"` // the latest encode failed; the outputs are older
	// ErrorCode is an image refusal's code (image_too_small, …) with its
	// details; empty when Error is a processing fault.
	ErrorCode    string        `json:"error_code,omitempty"`
	ErrorDetails *ErrorDetails `json:"error_details,omitempty"`
	// MinWidth is the narrowest edited width the slot accepts: croppers
	// keep crops at or above it.
	MinWidth int `json:"min_width,omitempty"`
	// Animation is the slot's policy: "reject" refuses animated images.
	Animation Animation `json:"animation,omitempty"`
}

type SlotRecord struct {
	Original string       `json:"original"`        // ETag of originals/{slot} when committed
	Edit     *Edit        `json:"edit,omitempty"`  // nil: the centred crop at the slot's Aspect
	Frame    *PosterFrame `json:"frame,omitempty"` // a video poster grabbed from a frame; nil for uploads
	Result   *SlotResult  `json:"result,omitempty"`
}

type SlotRefBody struct {
	Ref  RefBody `json:"ref"`
	Slot string  `json:"slot"`
}

type SlotRendition struct {
	Rung int `json:"rung"`
	W    int `json:"w"`
	H    int `json:"h"`
}

type SlotResult struct {
	Of      string          `json:"of"`              // the Fingerprint last encoded
	Source  string          `json:"source"`          // the original (ETag) Dims measure
	Dims    Dims            `json:"dims"`            // EXIF-oriented; zero when undecodable
	Outputs []SlotRendition `json:"outputs"`         // one per rung, ascending
	Error   string          `json:"error,omitempty"` // Of failed; Outputs are older
	// An image refusal's code and details; empty for a processing fault.
	Code    string        `json:"code,omitempty"`
	Details *ErrorDetails `json:"details,omitempty"`
}

type Spec struct {
	Width   int
	Height  int
	Fit     Fit
	Quality int
	Blur    float64
	// Unedited ignores the file's Edit: an editor's view of the whole source.
	// It must be EditorOnly.
	Unedited bool
	// EditorOnly variants are signed by the read API only for actors whose
	// Resolution is Editor; slots, inline images and zips cannot use them.
	EditorOnly bool
}

type Sprite struct {
	Blob     string  `json:"blob"`
	Cols     int     `json:"cols"`
	Rows     int     `json:"rows"`
	Width    int     `json:"w"`
	Height   int     `json:"h"`
	Interval float64 `json:"interval"`
}

type Staged struct {
	Name   string
	ETag   string
	SHA256 []byte
}

type Store interface {
	Put(ctx context.Context, key string, body io.Reader, size int64, opts PutOptions) (Object, error)
	Get(ctx context.Context, key string, opts GetOptions) (io.ReadCloser, Object, error)
	Head(ctx context.Context, key string) (Object, error)
	Delete(ctx context.Context, key string) error
	List(ctx context.Context, prefix string) iter.Seq2[Object, error]
	// Copy copies src to dst server-side, keeping its content type, cache
	// control and metadata; objects past the backend's single-copy limit
	// (5 GiB on S3) copy in parts. The returned Object has dst's size.
	Copy(ctx context.Context, src, dst string, o CopyOptions) (Object, error)

	PresignPut(ctx context.Context, key string, p PresignPut) (PresignedRequest, error)
	CreateMultipart(ctx context.Context, key, contentType string) (uploadID string, err error)
	PresignPart(ctx context.Context, key, uploadID string, number int32, size int64, sha256 []byte, ttl time.Duration) (PresignedRequest, error)
	// PutPart uploads one part from the server, bound to its length and SHA-256.
	PutPart(ctx context.Context, key, uploadID string, number int32, body io.Reader, size int64, sha256 []byte) (Part, error)
	ListParts(ctx context.Context, key, uploadID string) ([]Part, error)
	CompleteMultipart(ctx context.Context, key, uploadID string, parts []Part) (Object, error)
	AbortMultipart(ctx context.Context, key, uploadID string) error

	Capabilities() Capabilities
}

type Subtitle struct {
	ID     string `json:"id"`
	Lang   string `json:"lang,omitempty"`
	Label  string `json:"label,omitempty"`
	Forced bool   `json:"forced,omitempty"`
	Blob   string `json:"blob"`
}

type SweepResult struct {
	Deleted []string
	Wait    time.Duration
}

type SweepScheduler interface {
	ScheduleSweep(ctx context.Context, ref contentref.ContentRef) error
}

type TicketBody struct {
	Ticket string `json:"ticket"`
}

type UploadAuthorizer interface {
	CanUpload(ctx context.Context, actor access.Actor, ref contentref.ContentRef) (UploadGrant, error)
}

type UploadError struct {
	Code       string
	Message    string
	RetryAfter time.Duration // CodeRate: when the window frees
	Originals  []string      // CodeNotUploaded at commit: the originals to upload again
	Details    *ErrorDetails // image refusals
}

type UploadGrant struct {
	Allowed bool
	Exempt  bool
	Owner   string
}

type UploadHandlerOptions struct {
	Tenant string                                   // every ref is scoped to it
	Actor  func(*http.Request) (access.Actor, bool) // the host's authenticated caller; false answers 401
	Logger *slog.Logger                             // 5xx causes; default slog.Default()
	// Reader builds slot and video-image reply URLs (the access worker
	// origin; editor tokens for unpublished video posters); required for
	// slot and video routes.
	Reader *Reader
}

type UploadLimiter interface {
	Reserve(ctx context.Context, r Reservation) error
	Settle(ctx context.Context, s Settlement) error
}

type UploadOptions struct {
	Store      Store
	Kinds      *Registry
	Manifests  *Manifests
	Authorizer UploadAuthorizer
	Tickets    *token.Ring   // signs multipart tickets (domain-separated from access tokens); required for files over MaxSinglePut
	Limiter    UploadLimiter // optional
	Queue      ProcessQueue  // optional
	PresignTTL time.Duration // PUT and part URLs; default 15m
	// Grace is the sweep's (JobsConfig.Grace): the Manifests' Sweeps when it
	// is *Jobs, else 24h.
	Grace     time.Duration
	TicketTTL time.Duration // multipart ticket; default 24h, the abort-incomplete rule
	// Frames serves the video poster picker's frame grabs (media/video.Frames;
	// needs ffmpeg); nil answers not_found. FrameConcurrency bounds concurrent
	// grabs per process; default 2.
	Frames           FrameGrabber
	FrameConcurrency int
	// ProcessOnUpload tells the SDK to commit each manifest file as soon as
	// it is uploaded, unattached (Op.Unattached): the worker processes it
	// while the user is still arranging the upload, readers leave it out
	// until an attach op, and removing it discards its jobs and objects.
	// Quota is charged at that commit.
	ProcessOnUpload bool
}

type UploadedObject struct {
	Name string
	Type string
	Size int64
}

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

type Variant struct {
	Blob   string `json:"blob"`
	Spec   string `json:"spec,omitempty"`
	Type   string `json:"type,omitempty"`
	Size   int64  `json:"size,omitempty"`
	Editor bool   `json:"editor,omitempty"` // from Spec.EditorOnly: in editor/, signed for editors only
}

type Video struct {
	// Ladder is the rendition short sides (height of landscape, width of
	// vertical video), largest first; rungs above the source's short side
	// are dropped. Empty is DefaultLadder.
	Ladder []int `json:"ladder,omitempty"`
	// MinAspect and MaxAspect bound a source's display width/height; a
	// source outside fails permanently. Zero is DefaultMinAspect/DefaultMaxAspect.
	MinAspect float64 `json:"min_aspect,omitempty"`
	MaxAspect float64 `json:"max_aspect,omitempty"`
	// PosterWidths are the cover (poster slot) output widths, the host's
	// display sizes × densities; widths wider than the frame or upload are
	// skipped. Empty is DefaultPosterWidths.
	PosterWidths []int `json:"poster_widths,omitempty"`
	// Profile tunes the encode to the content: VideoLive (default) or
	// VideoAnimation (x264 tune animation, lower CRF, lower caps).
	Profile string `json:"profile,omitempty"`
}

type VideoImages struct {
	Poster PosterManifest `json:"poster"`
	Video  *VideoInfo     `json:"video,omitempty"`
	// Progress of the encode the outputs wait on (GET only, with
	// ReaderOptions.Progress): a file's run, then PhaseImages.
	Progress *EncodeProgress `json:"progress,omitempty"`
}

type VideoImagesBody struct {
	Ref  RefBody `json:"ref"`
	File string  `json:"file,omitempty"`
}

type VideoInfo struct {
	Version  string  `json:"version,omitempty"`
	File     string  `json:"file"`
	Duration float64 `json:"duration"`
	W        int     `json:"w"`
	H        int     `json:"h"`
	Encoded  bool    `json:"encoded"`
}

type VideoPosterBody struct {
	Ref    RefBody  `json:"ref"`
	Source string   `json:"source"`
	File   string   `json:"file,omitempty"`
	Time   *float64 `json:"time,omitempty"`
	SHA256 string   `json:"sha256,omitempty"`
	Edit   *Edit    `json:"edit,omitempty"`
}

type ViewerLimit struct {
	PerSecond float64
	Burst     int
	// Disabled turns limiting off, e.g. when the host limits upstream.
	Disabled bool
	// Redis is a Redis or Microsoft Garnet client shared by the replicas;
	// pass the host's own. Only INCR, PEXPIRE, GET, DECR and MULTI/EXEC are
	// used (no Lua: Garnet ships with scripting off).
	Redis redis.UniversalClient
	// KeyPrefix namespaces the Redis keys (default "contentkit:media:rl:").
	KeyPrefix string
}