media

type Animation string

type ArchiveStatus struct {
	ProcessingCount
	Pages *ProcessingCount `json:"pages,omitempty"`
}

type Aspect struct{ W, H int }

type Avatars struct {
	Kind   string `json:"kind"`
	Preset string `json:"preset"`
}

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"`
	OperationID string  `json:"operation_id"` // stable UUID for this complete ordered batch
	Ops         []Op    `json:"ops"`
}

type CommitReceipt struct {
	Operation string `json:"operation"`
	Attempt   string `json:"attempt"`
}

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,omitempty"`
	// Scope derives object roots and internal partitions; Namespace is legacy-only.
	Scope layout.Scope `json:"scope,omitzero"`
	// 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"`
	// Avatars names people's avatars: content shows them beside comment
	// authors and in moderation lists. Zero: people have none.
	Avatars Avatars `json:"avatars,omitzero"`
	// Editor is how editor views render (the whole oriented source the
	// cropper draws on); zero is DefaultEditor.
	Editor Image `json:"editor,omitzero"`
}

type CopyBody struct {
	Ref   RefBody       `json:"ref"`
	Files []CopyRequest `json:"files"`
}

type CopyFrom struct {
	Kind    string `json:"kind,omitempty"` // frame only
	ID      string `json:"id"`
	Version string `json:"version,omitempty"`
	Path    string `json:"path"`
}

type CopyOptions struct {
	IfMatch     string
	ContentType string
	// Metadata merges trusted operation receipts into the copied object's
	// existing metadata as part of the server-side copy itself.
	Metadata map[string]string
}

type CopyReply struct {
	Files []StagedCopy `json:"files"`
}

type CopyRequest struct {
	Path string `json:"path"`
	Type string `json:"type"`
	From string `json:"from"`
	Size int64  `json:"size,omitempty"` // checked when > 0
}

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 media gateway 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 DownloadState int

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

type EditorImage struct {
	Blob string `json:"blob"`
	FP   string `json:"fp"`
}

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, video_aspect_unsupported: the source's
	Height     int      `json:"height,omitempty"`      // image_too_large, video_too_large, video_aspect_unsupported: 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
	MinAspect  float64  `json:"min_aspect,omitempty"`  // video_aspect_unsupported: the narrowest width/height accepted
	MaxAspect  float64  `json:"max_aspect,omitempty"`  // video_aspect_unsupported: the widest width/height accepted
	Max        int      `json:"max,omitempty"`         // too_many_files: the files allowed; comment_too_long: the characters allowed
}

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}-{uuid}" 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:
	Admission  *SourceAdmission `json:"admission,omitempty"`  // verified ZIP source quota policy, never client-supplied
	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 a video (the frame op)
	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
	Public     []Publication    `json:"public,omitempty"`     // reserved or published public generations
	Editor     *EditorImage     `json:"editor,omitempty"`     // selected immutable editor view, never listed to ordinary readers

	// 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"`

	// Editors (editor reads and commit replies):
	PageID     string          `json:"page_id,omitempty"` // original page bytes' SHA-256, not filename, position or rendition hash
	CreateID   string          `json:"create_id,omitempty"`
	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"`
	From *CopyFrom `json:"from,omitempty"`
}

type GatewayRules struct {
	Namespaces []string
	// Scopes are the exact scoped roots; build gateway.Routes for these.
	Scopes   []layout.Scope
	Defaults []layout.Default
}

type GetOptions struct {
	IfNoneMatch string
	Range       string
}

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 Image struct {
	Format  ImageFormat `json:"format,omitempty"`
	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 ImageFormat string

type ImageQuery struct {
	Ref    contentref.ContentRef
	Preset string
	Name   string
}

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"`
	// Account places this kind in the tenant account root of a scoped registry.
	Account bool `json:"account,omitempty"`
	// Versions marks a content kind (ForContent). Each version owns its
	// folder; its parent content exists in the catalog, not in storage.
	Versions bool `json:"versions,omitempty"`
	// Publish describes the existing files a version's reader can use.
	// Published snapshots contain metadata, not separate media folders.
	Publish *Publish `json:"publish,omitempty"`
	Uploads []Upload `json:"uploads"`
	// KeepOriginals keeps an upload's blob once its private outputs exist;
	// version-owned content always retains its originals independently of this flag.
	// otherwise it is dropped (File.Gone). Public presets' sources are
	// always kept, so unhiding can render them again, as are body images,
	// which new versions copy.
	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"`
	// Downloads are the upload paths and private presets (Image, MP4 or Zip)
	// whose files live in download/: only a download token opens them and
	// reads never list them. ForContent adds a content kind's originals, its
	// zip and what the zip packs.
	Downloads []string `json:"downloads,omitempty"`
	// Download is what a version's download serves, one of Downloads: a
	// literal upload (the original) or an MP4 or Zip preset. ForContent sets
	// it from the content kind's download; "" serves none.
	Download string    `json:"download,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:"-"`
}

type LimitError struct{ RetryAfter time.Duration }

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

type MediaStatus struct {
	State        string              `json:"state"`
	Uploads      ProcessingCount     `json:"uploads"`
	Archives     ArchiveStatus       `json:"archives"`
	Presets      []PresetStatus      `json:"presets"`
	Encoding     *EncodeProgress     `json:"encoding,omitempty"`
	FailureCount int                 `json:"failure_count"`
	Failures     []ProcessingFailure `json:"failures"`
}

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 ObjectVersion struct {
	Key, VersionID string
}

type Op struct {
	Op         string         `json:"op"`
	SourceName string         `json:"source_name,omitempty"`
	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
	Replace    bool           `json:"replace,omitempty"`   // put: explicitly replace the target, including another source alias
	Index      *int           `json:"index,omitempty"`     // put, move, attach: among the attached uploads of its Upload
	Meta       map[string]any `json:"meta,omitempty"`      // put, copy: upload meta; attach: merged; meta: item meta; remove: auto_cover guards ownership
	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; frame: the video
	T          *float64       `json:"t,omitempty"`    // frame: the one a player shows t seconds in
	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 PageAnalysis struct {
	Recipe        string              `json:"recipe"`
	SourceSHA256  string              `json:"source_sha256"`
	Status        string              `json:"status"` // complete | unsupported | failed
	Width         int                 `json:"width,omitempty"`
	Height        int                 `json:"height,omitempty"`
	Frames        int                 `json:"frames,omitempty"`
	PixelSHA256   string              `json:"pixel_sha256,omitempty"`
	PixelFormat   string              `json:"pixel_format,omitempty"`
	ProfileSHA256 string              `json:"profile_sha256,omitempty"`
	Blank         string              `json:"blank"` // none | blank | suspected | unknown
	BlankReason   string              `json:"blank_reason,omitempty"`
	Confidence    string              `json:"confidence"` // exact | high | possible | unknown
	Metrics       PageAnalysisMetrics `json:"metrics,omitzero"`
	Flags         []string            `json:"flags,omitempty"`
}

type PageAnalysisMetrics struct {
	Pixels           uint64   `json:"pixels"`
	VisiblePixels    uint64   `json:"visible_pixels"`
	OpaquePixels     uint64   `json:"opaque_pixels"`
	ForegroundPixels uint64   `json:"foreground_pixels"`
	MinRGB           [3]uint8 `json:"min_rgb"`
	MaxRGB           [3]uint8 `json:"max_rgb"`
}

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 PresetRule struct {
	Kind      string `json:"kind"`
	Name      string `json:"name"`
	From      string `json:"from"`
	Base      string `json:"base"`
	Namespace string `json:"namespace"`
	// Root is the server-selected path before Kind, including its trailing slash.
	Root   string `json:"root,omitempty"`
	To     string `json:"to"`
	Widths []int  `json:"widths"`
	// Aspect is the rendition's shape ("W:H"); absent keeps the edit's.
	Aspect Aspect `json:"aspect,omitzero"`
	// MinWidth is the narrowest edit the preset accepts.
	MinWidth int `json:"min_width,omitempty"`
	// First makes it a preview: the first First uploads, {n} in To.
	First int `json:"first,omitempty"`
	// Default: the gateway serves the kind's default image at the template's
	// names while an item has no publication (Registry.DefaultImage).
	Default bool `json:"default"`
	// Stable: the template's names are also the current image's
	// (Public.Stable), so clients build its URLs from an item's id.
	Stable bool `json:"stable,omitempty"`
}

type PresetStatus struct {
	Name string `json:"name"`
	ProcessingCount
}

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"`
	SourceName      string          `json:"source_name,omitempty"`
	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
	SourceName      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/"). Source-format
	// images end in {ext}, the upload's extension: "download/{name}{ext}".
	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. Version
	// outputs stay in internal and can be served only by the authorized host
	// download transfer. They never share an allocation with ordinary served
	// outputs, because an item token opens every private file in its folder.
	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/"
	Subtitles *Subtitles `json:"subtitles,omitempty"`
	// Shapes render an Image preset's uploads of another shape: an upload
	// whose oriented size is in one renders its Image, any other (or one not
	// yet measured) renders Image. Shapes never overlap.
	Shapes []Shape `json:"shapes,omitempty"`
}

type ProcessingCount struct {
	Completed int `json:"completed"`
	Total     int `json:"total"`
	Failed    int `json:"failed"`
}

type ProcessingEvent struct {
	Kind         string          `json:"kind"`
	ContentID    string          `json:"content_id"`
	VersionID    string          `json:"version_id,omitempty"`
	State        string          `json:"state"`
	Uploads      ProcessingCount `json:"uploads"`
	Archives     ArchiveStatus   `json:"archives"`
	Presets      []PresetStatus  `json:"presets"`
	FailureCount int             `json:"failure_count"`
}

type ProcessingFailure struct {
	Path    string `json:"path"`
	Code    string `json:"code"`
	Message string `json:"message"`
}

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"`
	// Stable also keeps the current image at the logical names (To without
	// a generation), overwritten in place: a URL built from the item's id,
	// which the gateway answers with Default while none is current. One
	// image per item: no {name}, no First.
	Stable bool `json:"stable,omitempty"`
}

type PublicImage struct {
	From       string            `json:"from"`
	Preset     string            `json:"preset"`
	Renditions []PublicRendition `json:"renditions"`
}

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

type Publication struct {
	Preset string `json:"preset"`
	Source string `json:"source"` // the upload's Key
	FP     string `json:"fp"`
	// Stable records whether this generation also owns its logical names.
	// Nil marks historical manifests whose alias policy was not recorded.
	Stable *bool `json:"stable,omitempty"`
	// Generation suffixes every physical name; "" is a legacy publication,
	// files a pre-v0.68 worker wrote at the logical names (always ready).
	Generation string           `json:"generation"`
	Blobs      []string         `json:"blobs,omitempty"` // version preset outputs prepared in internal/, aligned with Names
	Names      []string         `json:"names"`           // logical preset names at this position
	State      PublicationState `json:"state"`
	Dims       []Dims           `json:"dims"`
}

type PublicationState uint8

type Publish struct {
	// Pages is the {name} upload of the version's ordered pages:
	// "originals/{name}".
	Pages string `json:"pages"`
	// Renditions are the private image presets from Pages a reader reads,
	// the first at reading size: "low", "thumb".
	Renditions []string `json:"renditions"`
	// Previews names a declared public preview preset (First caps the reader
	// preview count). Its uploads render normally; reader plans may also sign
	// existing private renditions under the live access policy.
	Previews string `json:"previews,omitempty"`
	// Playback is the declared {name} audio upload the reader plays unchanged.
	Playback string `json:"playback,omitempty"`
	// Import is the {name} upload of page archives (application/zip),
	// expanded into Pages in name order.
	Import string `json:"import,omitempty"`
	// Download is the HostOnly Zip preset of the version's pages, which a
	// download serves when its content kind serves pages.
	Download string `json:"download,omitempty"`
}

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

type ReadOptions struct {
	Prefix        string // only files under this path prefix ("low-res/")
	Offset, Limit int    // the range that gets URLs
	// Paths selects at most 64 exact file paths to receive URLs, independent
	// of ordinal position. All allowed metadata remains in manifest order.
	// It cannot be combined with a nonzero Offset or Limit.
	Paths    []string
	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, editor view and retained source URL, unattached ones
	// included. Source URLs are independent of the viewer's ServeOriginals.
	Editor bool
	// Status returns only whole-manifest processing counts, for editors.
	// It issues no URLs or editor-view work and ignores pagination/prefix.
	Status bool
}

type ReadResult struct {
	Access     string `json:"access"`
	Inspection bool   `json:"inspection,omitempty"` // explicit administrative view; playlists must repeat the management-read request
	// 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"`
	// Public lists the exact published renditions. Clients must not infer a
	// current cover or avatar's physical filename from the preset template.
	Public []PublicImage `json:"public,omitempty"`
	// Locked: the item holds files this viewer does not open. A viewer is
	// listed only the files it opens, so Total counts those alone.
	Locked bool `json:"locked,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"`
	// Status is a whole-manifest processing snapshot for editors only.
	Status *MediaStatus `json:"status,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"`
	// Uploads (editors) are the kind's upload paths and their rules.
	Uploads []UploadRule `json:"uploads,omitempty"`
	Files   []FileInfo   `json:"files"`
	// Cookie must be set on the response (cookie delivery, with access).
	Cookie *http.Cookie `json:"-"`
}

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"`
	Version string `json:"version,omitempty"`
}

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

type Segment struct {
	Offset  int64
	Length  int64
	Seconds float64
}

type Shape struct {
	WiderThan   Aspect `json:"wider_than,omitzero"`
	NoWiderThan Aspect `json:"no_wider_than,omitzero"`
	Image       Image  `json:"image"`
}

type SourceAdmission struct {
	// Generation is the accepting commit ID. Removing and re-adding a retained
	// ZIP creates fresh work; metadata edits keep the existing generation.
	Generation string `json:"generation"`
	Target     string `json:"target"`
	Accounting bool   `json:"accounting,omitempty"`
	Owner      string `json:"owner,omitempty"`
	Enforce    bool   `json:"enforce,omitempty"`
	Quota      int64  `json:"quota,omitempty"`
}

type Sprite struct {
	Cols     int     `json:"cols"`
	Rows     int     `json:"rows"`
	W        int     `json:"w"`
	H        int     `json:"h"`
	Interval float64 `json:"interval"`
}

type StagedCopy struct {
	Path string `json:"path"`
	Blob string `json:"blob"`
	Size int64  `json:"size"`
}

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 (unless
	// o.ContentType), 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 are the backend's, probed on first use when not given; an
	// error (ErrUnavailable) means they are not known yet.
	Capabilities(ctx context.Context) (Capabilities, error)
	// Check reports whether the backend answers, establishing Capabilities
	// while they are unknown.
	Check(ctx context.Context) error
}

type Subtitles struct{}

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}-{uuid}": the TrackIndex
}

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

type Upload struct {
	Path string `json:"path"`
	// ArchiveTo expands a ZIP into this image upload pattern during ingestion.
	// It is media-level policy and may target gallery pages or body images.
	ArchiveTo string `json:"archive_to,omitempty" yaml:"archive_to"`
	// Body marks a content kind's body images (Named, with a private image
	// preset and no public one): each version keeps its copy in private/,
	// which only the version's openers read.
	Body     bool     `json:"body,omitempty"`
	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 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
	// ArchiveTo explicitly approves every generated filename in this configured
	// destination pattern. Empty does not authorize expansion.
	ArchiveTo string
}

type UploadRule struct {
	Path     string   `json:"path"`
	Types    []string `json:"types"`
	MaxBytes int64    `json:"max_bytes"`
	// Max caps the files at Path; 0 is unlimited.
	Max   int  `json:"max,omitempty"`
	Named bool `json:"named,omitempty"`
	Page  bool `json:"page,omitempty"` // original pages of a versioned reader
	// Body: the upload holds the body's images (Upload.Body).
	Body   bool   `json:"body,omitempty"`
	Frames string `json:"frames,omitempty"`
	// Aspect and MinWidth bound an image's edit: its first public preset's.
	Aspect   Aspect `json:"aspect,omitzero"`
	MinWidth int    `json:"min_width,omitempty"`
	// Video is a video upload's limits in effect; MinAspect and
	// MaxAspect the display aspects (width/height) its HLS presets accept.
	Video     *VideoLimits `json:"video,omitempty"`
	MinAspect float64      `json:"min_aspect,omitempty"`
	MaxAspect float64      `json:"max_aspect,omitempty"`
}

type UploadTarget struct {
	Ref  contentref.ContentRef
	Path string
}

type VideoJobClass string

type VideoLimits struct {
	MaxSeconds float64 `json:"max_seconds,omitempty"` // real running time
	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"`
}