media

type AgentRules struct {
	Namespaces []string
	Defaults   []layout.Default
}

type Animation string

type Aspect struct{ W, H int }

type Audio struct {
	// Loudness normalizes to this integrated loudness in LUFS (EBU R128),
	// e.g. -16; 0 keeps the source's level.
	Loudness float64 `json:"loudness,omitempty"`
}

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

type Codec string

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

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

type CompleteReply struct {
	Blob string `json:"blob"`
	Type string `json:"type"`
	Size int64  `json:"size"`
}

type Config struct {
	// Namespace is the app's own namespace, e.g. "doujins": its kinds' items
	// live under {Namespace}/{kind}/{id}/.
	Namespace string `json:"namespace"`
	// BaseURL is the site's media origin, e.g. "https://media.doujins.ai":
	// every URL is {BaseURL}/v1/{namespace}/{kind}/{id}/{public|private}/{name}.
	BaseURL string `json:"base_url,omitempty"`
	// Kinds are the app's kinds plus the shared kinds it imports.
	Kinds []Kind `json:"kinds"`
	// Editor is how editor views render (the whole oriented source the
	// cropper draws on); zero is DefaultEditor.
	Editor Image `json:"editor,omitzero"`
	Hooks  Hooks `json:"-"`
}

type CopyFrom struct {
	ID   string `json:"id"`
	Path string `json:"path"`
}

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
	OperationID string // required by Purge with a quota owner; stable across retries
}

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

type DeliveryMode string

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

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: each rung is published before the next one starts.
	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, video_too_large: the source's
	Height     int      `json:"height,omitempty"`      // image_too_large, video_too_large: the source's
	MinWidth   int      `json:"min_width,omitempty"`   // image_too_small
	MaxPixels  int      `json:"max_pixels,omitempty"`  // image_too_large, video_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, video_too_long: running time
	MaxSeconds float64  `json:"max_seconds,omitempty"` // animation_too_long, video_too_long
}

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

type Failure struct {
	Of      string        `json:"of"` // File.Key it was recorded for
	Message string        `json:"message"`
	Code    string        `json:"code,omitempty"` // an ImageError's code
	Details *ErrorDetails `json:"details,omitempty"`
}

type File struct {
	Path string  `json:"path"`           // app path: "originals/001.png", "low-res/001.webp"
	Blob string  `json:"blob,omitempty"` // "sha256-{hex}" in private/; "" for a staged upload or a frame not grabbed yet
	Type string  `json:"type"`
	Size int64   `json:"size,omitempty"`
	W    int     `json:"w,omitempty"` // an upload's oriented size once measured; an output's size
	H    int     `json:"h,omitempty"`
	Dur  float64 `json:"dur,omitempty"`

	// Uploads:
	Staged     string         `json:"staged,omitempty"`     // "u-{uuid}" in temp/ until the worker hashes and places it at Blob
	CreateID   string         `json:"create_id,omitempty"`  // create-only put receipt; retained through placement and processing
	Edit       *Edit          `json:"edit,omitempty"`       // crop and rotate in source pixels
	Frame      *Frame         `json:"frame,omitempty"`      // grabbed from the Upload.Frames video
	Meta       map[string]any `json:"meta,omitempty"`       // lang, label, …
	Unattached bool           `json:"unattached,omitempty"` // processed on upload, not yet part of the item
	Gone       bool           `json:"gone,omitempty"`       // blob dropped (KeepOriginals false); the hash stays for provenance
	Pending    []string       `json:"pending,omitempty"`    // presets still producing from this upload
	Failed     *Failure       `json:"failed,omitempty"`     // this blob and edit cannot be processed

	// Derived files:
	From     string `json:"from,omitempty"`     // the upload's path, or a zip's prefix
	Preset   string `json:"preset,omitempty"`   // the Private preset
	FP       string `json:"fp,omitempty"`       // Fingerprint of its inputs
	Download string `json:"download,omitempty"` // the human download name
	Track    *Track `json:"track,omitempty"`    // HLS
}

type FileInfo struct {
	Path     string  `json:"path"`
	Type     string  `json:"type"`
	Size     int64   `json:"size,omitempty"`
	W        int     `json:"w,omitempty"`
	H        int     `json:"h,omitempty"`
	Dur      float64 `json:"dur,omitempty"`
	Download string  `json:"download,omitempty"` // the name a download read serves it under
	URL      string  `json:"url,omitempty"`
	Locked   bool    `json:"locked,omitempty"`

	// Editors (editor reads and commit replies):
	Upload     bool            `json:"upload,omitempty"`
	Staged     bool            `json:"staged,omitempty"` // uploaded, not yet placed by the worker: no blob, views or frames yet
	From       string          `json:"from,omitempty"`
	Edit       *Edit           `json:"edit,omitempty"`
	Frame      *Frame          `json:"frame,omitempty"`
	Meta       map[string]any  `json:"meta,omitempty"`
	Unattached bool            `json:"unattached,omitempty"`
	Pending    []string        `json:"pending,omitempty"`
	Failed     *Failure        `json:"failed,omitempty"`
	EditorURL  string          `json:"editor_url,omitempty"`
	Progress   *EncodeProgress `json:"progress,omitempty"`
}

type FitMode string

type FolderNotEmptyError struct {
	Prefix string
	Keys   []string
}

type Frame struct {
	T    float64 `json:"t,omitempty"`
	Auto bool    `json:"auto,omitempty"`
	Of   string  `json:"of,omitempty"`
}

type FrameGrabber interface {
	Frame(ctx context.Context, item Item, video 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 {
	// Ladder is the rendition short sides, largest first; empty is DefaultLadder.
	Ladder []int `json:"ladder,omitempty"`
	// MinAspect and MaxAspect bound the source's display width/height; zero
	// is DefaultMinAspect and DefaultMaxAspect. A source outside fails.
	MinAspect float64 `json:"min_aspect,omitempty"`
	MaxAspect float64 `json:"max_aspect,omitempty"`
	Profile   string  `json:"profile,omitempty"` // VideoLive or VideoAnimation
}

type HandlerOptions struct {
	Identity Identity
	Logger   *slog.Logger
	// Limit is the per-viewer rate limit (default 2/s, burst 120, per
	// process; set Limit.Redis to share it across replicas): every read,
	// playlist and download counts.
	// Viewers are keyed by Actor.ID, anonymous ones by Actor.IP, else by the
	// connection's address.
	Limit RateLimit
}

type Hooks struct {
	// Resolver says who may see an item: the read API, Expose and a new
	// item's first commit (Uploads) use it, and both require it.
	Resolver access.ContentResolver
	// CanUpload says who may write which upload path.
	CanUpload UploadAuthorizer
	// PurgePublic hears of public URLs overwritten, deleted or first
	// written (the CDN may hold the default), for a CDN purge.
	PurgePublic func(ctx context.Context, urls []string)
	// ItemReady reports an item whose processing settled (ready, or failed
	// with nothing processing) in a host transaction, after the worker's
	// job, through the host's media queue. It must be idempotent; an error
	// retries.
	ItemReady func(ctx context.Context, tx pgx.Tx, ref contentref.ContentRef, r Readiness) error
	// Failed reports an upload a producer cannot process, where it runs.
	Failed func(ctx context.Context, ref contentref.ContentRef, path string, err error)
}

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

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

type Image struct {
	Width   int     `json:"width,omitempty"`
	Height  int     `json:"height,omitempty"`
	Fit     FitMode `json:"fit,omitempty"`
	Quality int     `json:"quality,omitempty"` // default 80
	Blur    float64 `json:"blur,omitempty"`
	// Aspect and MinWidth bound an upload's edit when this is its public
	// preset's image: the crop is fitted to Aspect, and an edit narrower
	// than MinWidth fails.
	Aspect    Aspect    `json:"aspect,omitzero"`
	MinWidth  int       `json:"min_width,omitempty"`
	Animation Animation `json:"animation,omitempty"`
}

type ImageError struct {
	Code    string
	Message string
	Details ErrorDetails
}

type IngestRequest struct {
	Ref  contentref.ContentRef
	Path 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
	Meta map[string]any

	// Resume continues a multipart write 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 write 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 {
	Staged   string
	Size     int64
	Manifest *Manifest
}

type IngestUpload struct {
	Temp     string `json:"temp"` // the staged name (u-{uuid})
	UploadID string `json:"upload_id"`
}

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

type Issuance struct {
	// PerHour is the items an account may open per hour (default 120);
	// AnonymousPerHour is per Actor.IP (an IPv6 address counts as its /64),
	// where one address may be many people (default 600). The read API
	// fills an anonymous actor's IP from the connection; a host calling
	// Reader.Grant itself must set it (ErrNoViewerKey otherwise: without it
	// every anonymous viewer would share one count).
	PerHour, AnonymousPerHour int
	Disabled                  bool
	// Exempt actors are not limited (staff); an item's editors never are.
	Exempt func(access.Actor) bool
	// Redis is a Redis or Microsoft Garnet client shared by the replicas.
	// Only SADD, SCARD, SREM, PEXPIRE and MULTI/EXEC are used (no Lua).
	Redis redis.UniversalClient
	// KeyPrefix namespaces the Redis keys (default "contentkit:media:issue:").
	KeyPrefix string
}

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

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

type JobsConfig struct {
	Store     Store
	Registry  *Registry
	Locker    Locker       // serializes manifest edits and sweep deletion; required
	Processes ProcessQueue // the worker's queue (workqueue.Queue): Expose and Regenerate render through it
	// Pool is the host database Hooks.ItemReady's transaction runs on;
	// required with ItemReady.
	Pool *pgxpool.Pool
	// Grace protects job outputs not recorded yet: the sweep deletes an
	// unreferenced blob once it is this old, whatever edits follow. Default
	// 24 h.
	Grace time.Duration
	// TempTTL is how long temp/ objects (in-flight server-side writes) are
	// kept; above the bucket's 1-day abort-incomplete rule. Default 48 h.
	TempTTL time.Duration
	// SweepInterval is the periodic pass over every folder. Default 24 h.
	SweepInterval time.Duration
	// LateUploadWindow delays a folder deletion's second pass, which removes
	// uploads that land after the first; above the presign TTL and the
	// 1-day multipart rule. Default 25 h.
	LateUploadWindow time.Duration
	Limiter          QuotaReleaser // releases a deleted item's quota; optional
	Queue            string        // default DefaultQueue
	MaxWorkers       int           // default 2
	Logger           *slog.Logger
	Now              func() time.Time
}

type Kind struct {
	Name string `json:"name"`
	// Namespace is "" for Config.Namespace, or a shared one such as
	// "accounts" whose items every app importing the kind serves.
	Namespace string   `json:"namespace,omitempty"`
	Uploads   []Upload `json:"uploads"`
	// KeepOriginals keeps an upload's blob once its private outputs exist;
	// otherwise it is dropped (File.Gone). Public presets' sources are
	// always kept, so unhiding can render them again.
	KeepOriginals bool `json:"keep_originals,omitempty"`
	// ServeOriginals lists and serves uploads to viewers with access, like
	// any private file. Otherwise viewer URLs are scoped to served files,
	// not the whole private folder, and reads omit upload paths and blobs.
	ServeOriginals bool      `json:"serve_originals,omitempty"`
	Private        []Private `json:"private,omitempty"`
	Public         []Public  `json:"public,omitempty"`
	// Defaults holds the images the kind's public presets name in
	// Public.Default, so a shared kind ships its own (go:embed). A registry
	// read from JSON (the stock worker) has none; PublishDefaults needs them.
	Defaults fs.FS `json:"-"`
	// contains filtered or unexported fields
}

type LimitError struct{ RetryAfter time.Duration }

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

type MP4 struct {
	Rung    int    `json:"rung"`
	Profile string `json:"profile,omitempty"`
}

type Manifest struct {
	V      int  `json:"v"`
	Hidden bool `json:"hidden,omitempty"` // set by Expose; public files are then absent
	// Full: a producer could not record its outputs within the bound, so
	// private outputs stop until a commit frees Deficit bytes (in the
	// manifest and in what its uploads would still add): how far past the
	// bound the refused record went.
	Full    bool           `json:"full,omitempty"`
	Deficit int64          `json:"deficit,omitempty"`
	Meta    map[string]any `json:"meta,omitempty"` // the app's template values, e.g. title
	Files   []File         `json:"files"`
	// contains filtered or unexported fields
}

type ManifestOptions struct {
	// Locker is required: every edit runs under it, and also writes with
	// If-Match once the store reports ConditionalPut. See PGLocker.
	Locker Locker
	// CacheBytes bounds the decoded manifests kept in process, revalidated
	// by ETag. A manifest costs about three times its JSON, so the largest
	// (MaxManifestBytes) costs 24 MiB; default 128 MiB, at least two of them.
	CacheBytes int64
	MaxRetries int // conditional-write attempts per edit; default 16
	// Sweeps schedules the folder's sweep after every written edit; best
	// effort (the periodic 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"`
	Path       string         `json:"path,omitempty"`
	Blob       string         `json:"blob,omitempty"`      // put: the staged upload (u-{uuid}) or a blob in the folder
	CreateID   string         `json:"create_id,omitempty"` // put: create-only UUID; repeat the same ID to retry
	Index      *int           `json:"index,omitempty"`     // put, move, attach: among the attached uploads of its Upload
	Meta       map[string]any `json:"meta,omitempty"`      // put: the upload's meta; attach: merged into it; meta: the item's
	Edit       *Edit          `json:"edit,omitempty"`      // put, edit, copy, frame
	Unattached bool           `json:"unattached,omitempty"`
	To         string         `json:"to,omitempty"`   // rename, copy (default the source's path)
	From       *CopyFrom      `json:"from,omitempty"` // copy
	T          *float64       `json:"t,omitempty"`    // frame: seconds into the video
	Auto       bool           `json:"auto,omitempty"` // frame: the worker chooses
	Preset     string         `json:"preset,omitempty"`
	Force      bool           `json:"force,omitempty"`
	// Takedown (remove) also removes the frames grabbed from the upload and
	// the zips that bundled it, then deletes at once, not a grace period
	// later, the blobs the commit dropped, the removed uploads' editor views
	// and the public files no upload renders. With an exempt grant it deletes
	// every private blob the item no longer references (earlier versions and
	// every editor view too), and repeating it, the path already gone, runs
	// that sweep again: how staff complete a takedown that failed part way.
	Takedown bool `json:"takedown,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 {
	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 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 PresignBody struct {
	Ref    RefBody `json:"ref"`
	Path   string  `json:"path"`
	Type   string  `json:"type"`
	Size   int64   `json:"size"`
	SHA256 string  `json:"sha256"`
}

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

type PresignReply struct {
	Path            string          `json:"path"`
	Blob            string          `json:"blob"`
	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
	Path   string
	Type   string
	Size   int64
	SHA256 []byte
}

type Presigned struct {
	Path            string
	Blob            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 Private struct {
	Name string `json:"name"`
	// From is an upload path or pattern; "" for Zip.
	From string `json:"from,omitempty"`
	// To is the output path template: a file ("low-res/{name}.webp",
	// "video/source-1080p.mp4") or, for producers with several outputs, a
	// directory ending in "/" ("hls/", "listen/{name}/").
	To string `json:"to"`
	// Download is the human name template a download read signs into the
	// URL, filled from the manifest's meta and {name}: "{title}.zip".
	Download string `json:"download,omitempty"`
	// HostOnly leaves this preset out of generic reads and playlists; a host
	// route applies its own policy and calls Grant.HostURL. It decides what
	// is listed, not what a token opens: an item's token opens every private
	// file of the item.
	HostOnly  bool       `json:"host_only,omitempty"`
	Image     *Image     `json:"image,omitempty"`
	HLS       *HLS       `json:"hls,omitempty"`
	MP4       *MP4       `json:"mp4,omitempty"`
	Zip       string     `json:"zip,omitempty"` // the files under this prefix, in manifest order: "high/"
	Audio     *Audio     `json:"audio,omitempty"`
	Subtitles *Subtitles `json:"subtitles,omitempty"`
	// Choose is an optional per-file image spec (Go only, not in the JSON
	// registry); nil keeps Image.
	Choose func(f File) *Image `json:"-"`
}

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

type ProcessJob struct {
	Ref    contentref.ContentRef `json:"ref"`
	Place  bool                  `json:"place,omitempty"`
	Preset string                `json:"preset,omitempty"` // only this preset; "" for all
	Force  bool                  `json:"force,omitempty"`  // redo current outputs too
	Editor bool                  `json:"editor,omitempty"` // also render missing editor views
	Class  VideoJobClass         `json:"class,omitempty"`
}

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

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

type Public struct {
	Name   string `json:"name"`
	From   string `json:"from"`
	To     string `json:"to"` // "cover-{w}.webp", "{name}.webp", "preview-{n}.webp"
	First  int    `json:"first,omitempty"`
	Widths []int  `json:"widths,omitempty"`
	Image  Image  `json:"image"`
	// Default is a path in Kind.Defaults, rendered to the kind's _default
	// item at every width (PublishDefaults).
	Default string `json:"default,omitempty"`
}

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

type QuotaRelease struct {
	Tenant    string
	Folder    string
	Owner     string
	Operation string
	Bytes     int64
}

type QuotaReleaser interface {
	PrepareRelease(ctx context.Context, r QuotaRelease) (applied bool, err error)
	Release(ctx context.Context, tenant, operation string) error
}

type RateLimit 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 (defaults "contentkit:media:rl:"
	// for viewers, "contentkit:media:commit:" for uploaders).
	KeyPrefix string
}

type ReadOptions struct {
	Prefix        string // only files under this path prefix ("low-res/")
	Offset, Limit int    // the range that gets URLs
	Download      bool   // URLs serve each file as a download under its name
	// Editor adds an editor's uploads with their edit, frame, meta,
	// pending, failure and editor view, unattached ones included.
	Editor bool
}

type ReadResult struct {
	Access string `json:"access"`
	// Expires is when the item token (the URLs, the cookie) stops working,
	// in unix seconds. A read before then answers the same token, so a
	// client keeps what it has and reads again shortly before.
	Expires int64          `json:"expires"`
	Meta    map[string]any `json:"meta,omitempty"`
	// Previews are the item's public preview images in order (a Public
	// preset with First): every viewer who can see the item gets them.
	Previews []string `json:"previews,omitempty"`
	Total    int      `json:"total"`
	Offset   int      `json:"offset"`
	Limit    int      `json:"limit"`
	// HLS lists the item's playable ladders by output directory ("hls/"):
	// play {read API}/{kind}/{id}/hls/{dir}master.m3u8.
	HLS []string `json:"hls,omitempty"`
	// State is the item's readiness (editors).
	State string `json:"state,omitempty"`
	// Full (editors): the item's manifest cannot hold more outputs, so
	// processing stopped; remove uploads (any commit that shrinks it) to
	// resume. Uploads left unprocessed stay pending.
	Full  bool       `json:"full,omitempty"`
	Files []FileInfo `json:"files"`
	// Cookie must be set on the response (cookie delivery, with access).
	Cookie *http.Cookie `json:"-"`
}

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

type ReaderOptions struct {
	Manifests *Manifests // its Registry's BaseURL and Hooks.Resolver are required
	Delivery  Delivery
	// Progress adds live encode progress to pending uploads in editor
	// reads; optional.
	Progress ProgressSource
	// Queue renders the editor views an editor read finds missing; optional.
	Queue ProcessQueue
	// MaxLimit caps ReadOptions.Limit (default 200); DefaultLimit is used
	// when Limit is 0 (default 50).
	MaxLimit, DefaultLimit int
	// IndexCacheBytes bounds the track index blobs kept for playlists;
	// default 16 MiB.
	IndexCacheBytes int64
	// Issuance limits the items each viewer is given access to per hour
	// (default 120 per account, 600 per anonymous IP).
	Issuance Issuance
	Now      func() time.Time
}

type Readiness struct {
	State      string   `json:"state"`
	Processing []string `json:"processing,omitempty"`
	Failed     []string `json:"failed,omitempty"`
}

type RefBody struct {
	Kind string `json:"kind"`
	ID   string `json:"id"`
}

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

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 Sprite struct {
	Cols     int     `json:"cols"`
	Rows     int     `json:"rows"`
	W        int     `json:"w"`
	H        int     `json:"h"`
	Interval float64 `json:"interval"`
}

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)
	// PresignGet is for a worker reading an original over HTTP ranges. Its URL
	// uses the store's internal endpoint and must not be returned to browsers.
	PresignGet(ctx context.Context, key string, ttl time.Duration) (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
	// Check reports whether the backend answers. The first success also
	// establishes Capabilities (Probe under prefix) when they were not given.
	Check(ctx context.Context, prefix string) error
}

type Subtitles struct{}

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 Track struct {
	Kind      string `json:"kind"`             // TrackVideo, TrackAudio, TrackSubs, TrackSprite
	Codec     string `json:"codec,omitempty"`  // video: h264, hevc, av1
	Codecs    string `json:"codecs,omitempty"` // RFC 6381
	Bandwidth int    `json:"bw,omitempty"`
	Average   int    `json:"avg,omitempty"`
	ID        string `json:"id,omitempty"`
	Lang      string `json:"lang,omitempty"`
	Label     string `json:"label,omitempty"`
	Default   bool   `json:"default,omitempty"`
	Forced    bool   `json:"forced,omitempty"`
	Index     string `json:"index,omitempty"` // "sha256-{hex}": the TrackIndex
}

type TrackIndex struct {
	Segments []Segment `json:"segments,omitempty"`
	Sprite   *Sprite   `json:"sprite,omitempty"`
}

type Unreferenced struct {
	// All is every private blob in the folder, editor views included: a
	// worker whose unrecorded outputs go with them finds them missing when
	// it records, and produces them again.
	All bool
	// Blobs are candidates: each goes unless it is an editor view of a
	// current upload.
	Blobs []string
	// Staged are staged uploads' names.
	Staged []string
}

type Upload struct {
	Path     string   `json:"path"`
	Types    []string `json:"types"`            // accepted content types
	MaxBytes int64    `json:"max_bytes"`        // per file
	Max      int      `json:"max,omitempty"`    // uploads matching Path; 0 is unlimited
	Frames   string   `json:"frames,omitempty"` // may be grabbed from a frame of this video upload (the frame op)
	Named    bool     `json:"named,omitempty"`  // the server names it ({name} is "i-{uuid}"): inline images
	// Video bounds a video or audio upload as probed from its real stream;
	// nil or zero fields take the defaults (DefaultVideoLimits).
	Video *VideoLimits `json:"video,omitempty"`
}

type UploadAuthorizer interface {
	CanUpload(ctx context.Context, actor access.Actor, t UploadTarget) (UploadGrant, error)
}

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

type UploadGrant struct {
	Allowed bool
	Exempt  bool
	Owner   string
}

type UploadHandlerOptions struct {
	Actor  func(*http.Request) (access.Actor, bool) // the host's authenticated caller; false answers 401
	Logger *slog.Logger                             // 5xx causes; default slog.Default()
}

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

type UploadOptions struct {
	Store     Store
	Manifests *Manifests    // its Registry's Hooks.CanUpload authorizes, Hooks.Resolver hides new items
	Tickets   *token.Ring   // signs multipart tickets (domain-separated from access tokens); required above MaxSinglePut
	Limiter   UploadLimiter // optional
	Queue     ProcessQueue  // places staged uploads and processes items in the media worker; required
	// PresignTTL bounds PUT and part URLs; default 15m. TicketTTL bounds a
	// multipart ticket; default 24h, the bucket's abort-incomplete rule.
	PresignTTL, TicketTTL time.Duration
	// Grace is the sweep's (JobsConfig.Grace): an existing blob is reused
	// only while the sweep cannot take it first. Default 24h.
	Grace time.Duration
	// Frames serves the frame picker (media/video.Frames); nil answers
	// not_found. FrameConcurrency bounds grabs per process; default 2.
	Frames           FrameGrabber
	FrameConcurrency int
	// ProcessOnUpload tells the SDK to commit each upload unattached as
	// soon as it lands, so the worker processes it while the user arranges
	// the rest; an attach op makes it part of the item.
	ProcessOnUpload bool
	// Commits limits each uploader's commits (default 1/s, burst 30, per
	// process; set Commits.Redis to share it); exempt grants are not
	// limited.
	Commits RateLimit
}

type UploadTarget struct {
	Ref  contentref.ContentRef
	Path string
}

type UploadedBlob struct {
	Blob string
	Type string
	Size int64
}

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

type VideoJobClass string

type VideoLimits struct {
	MaxSeconds float64 `json:"max_seconds,omitempty"` // real running time (audio too)
	MaxFPS     float64 `json:"max_fps,omitempty"`     // output frame rate (at most 60); a faster source is encoded at it
	MaxPixels  int     `json:"max_pixels,omitempty"`  // displayed frame area
	// MaxWork bounds the planned encode: the sum over the HLS and MP4
	// presets' rungs and codecs of output pixels × output frames.
	MaxWork float64 `json:"max_work,omitempty"`
}