blob

type AccessStore interface {
	// Grant records that the grant's principal may exercise its permission on its
	// blob. It is idempotent: re-granting the same (blob, principal, permission)
	// is a no-op. It returns ErrInvalidGrant if the grant is not well-formed.
	Grant(ctx context.Context, g *Grant) error

	// HasGrant reports whether a grant exists for the exact (blob, principal,
	// permission) triple. A missing grant is (false, nil), not an error. It
	// returns ErrInvalidGrant if the lookup key is not well-formed.
	HasGrant(ctx context.Context, blobID *blobpb.BlobId, p Principal, perm Permission) (bool, error)

	// Revoke removes a grant. It is idempotent: revoking a grant that does not
	// exist is a no-op. It returns ErrInvalidGrant if the key is not well-formed.
	Revoke(ctx context.Context, blobID *blobpb.BlobId, p Principal, perm Permission) error
}

type Blob struct {
	ID *blobpb.BlobId

	// Rendition is which rendition of its media this blob holds. An ORIGINAL has
	// a nil ParentID; any other rendition type is a server-derived variant with
	// ParentID pointing at the original.
	Rendition RenditionType

	// ParentID is set when this blob is a server-derived rendition of another
	// blob; it points at the ORIGINAL the client uploaded. It is nil for an
	// ORIGINAL. Renditions are never uploaded by clients — the server derives
	// them from the original's bytes.
	ParentID *blobpb.BlobId

	Owner *commonpb.UserId

	// State is the blob's internal lifecycle state — the source of truth for how
	// far processing has progressed. The public blobpb.BlobStatus is derived from
	// it via State.ToBlobStatus.
	State State

	// StorageKey is the object key the bytes live under in the backing store. It
	// is derived from the ID and never leaves the server.
	StorageKey string

	// MimeType is the declared MIME type, pinned at reservation and immutable.
	MimeType string

	// SizeBytes is the declared size, pinned at reservation and immutable.
	SizeBytes uint64

	// Image is the derived IMAGE metadata, set only when this blob is an image
	// and READY. It is the image variant of the blob's kind-specific metadata;
	// as additional content kinds are supported they will be carried by their
	// own sibling fields here (e.g. Video, Audio), one per blobpb.BlobMetadata
	// kind variant. Only images exist today.
	Image *ImageMetadata

	// Renditions is the manifest of derived renditions, populated ONLY on an
	// ORIGINAL and only once its renditions have been generated. Each entry is a
	// compact, immutable copy of a child rendition blob's servable metadata,
	// denormalized onto the parent so a media's whole rendition set resolves in the
	// single read that fetches the original — no per-original index query. The child
	// rendition blobs remain the canonical, independently-addressable records (a
	// rendition id resolves through GetBlobs and inherits the parent's ACL); this is
	// purely a read-path manifest. It is nil on a rendition blob itself and on an
	// original whose ladder produced nothing.
	Renditions []RenditionRef

	// Rejection records why this blob was rejected, set only when State is
	// StateRejected; it is nil for any non-rejected blob.
	Rejection *RejectionMetadata
}

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

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

type ContentKind int

type FinalizationQueueStats struct {
	// Depth is how many blobs are queued, due or not — a delayed retry is
	// still backlog.
	Depth uint64

	// OldestEnqueuedAt is when the longest-queued blob was FIRST enqueued; its
	// distance from now is the queue's max age. Re-marks and retry delays never
	// reset it, so it exposes a blob stuck cycling through backoff — which the
	// depth alone hides. It is the zero time when the queue is empty.
	OldestEnqueuedAt time.Time
}

type FinalizationTask struct {
	ID *blobpb.BlobId

	// Attempts is the number of failed finalization attempts recorded so far
	// (via DelayFinalization). The worker uses it to pace backoff and to stop
	// retrying an unfinalizable blob.
	Attempts uint32

	// NextAttemptAt is when the task next becomes due.
	NextAttemptAt time.Time
}

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

type Grant struct {
	BlobID     *blobpb.BlobId
	Principal  Principal
	Permission Permission
}

type ImageInspection struct {
	MimeType string
	Metadata *ImageMetadata

	// Decoded is the decoded image, retained so callers can derive other
	// renderings (e.g. the moderation payload) without decoding the bytes again.
	Decoded image.Image
}

type ImageMetadata struct {
	Width    uint32
	Height   uint32
	Blurhash string
	HasAlpha bool
}

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

type ObjectStorage interface {
	// PresignUpload mints a short-lived, presigned target the client uploads the
	// bytes to directly, into the UPLOAD store under the given key. The target
	// pins the declared content type and exact size, so storage rejects any
	// upload that does not match.
	PresignUpload(ctx context.Context, key, mimeType string, sizeBytes uint64) (*blobpb.UploadTarget, error)

	// GetUploaded returns the bytes a client uploaded under the key in the UPLOAD
	// store, or ErrObjectNotFound if no bytes are present yet. Finalization reads
	// them back to validate the content before promoting it.
	GetUploaded(ctx context.Context, key string) ([]byte, error)

	// UploadExists reports whether bytes are present under the key in the UPLOAD
	// store, without fetching them. Completion uses it to cheaply distinguish an
	// upload that landed from one that never happened before queueing the blob
	// for finalization.
	UploadExists(ctx context.Context, key string) (bool, error)

	// CopyToOrigin copies a validated object from the UPLOAD store to the ORIGIN
	// store under the same key, making it servable through the CDN. It overwrites
	// any object already served under the key, so it is safe to call more than
	// once. The upload copy is intentionally left in place — the caller removes it
	// with DeleteUpload only after the blob's terminal state is durably recorded,
	// so an interrupted finalization is always replayable from the upload bytes.
	CopyToOrigin(ctx context.Context, key string) error

	// PutOrigin writes server-derived bytes directly into the ORIGIN store under
	// the given key, pinning the content type so the CDN serves them correctly. It
	// is how derived renditions land: unlike a client upload, these bytes were
	// produced by the server from an original that already passed inspection and
	// moderation, so they are trusted and bypass the upload quarantine entirely
	// rather than being staged and copied. It overwrites any object already under
	// the key, so a replayed finalization that regenerates a rendition is
	// idempotent.
	PutOrigin(ctx context.Context, key, mimeType string, data []byte) error

	// DeleteUpload removes an object from the UPLOAD store. It is best-effort
	// cleanup run after a blob reaches a terminal state, and is idempotent:
	// deleting an absent key is not an error.
	DeleteUpload(ctx context.Context, key string) error

	// SignDownloadURL mints a fresh, short-lived CDN URL for fetching a promoted
	// object's bytes from the ORIGIN store, paired with the instant it expires. It
	// is authorized at mint time and expires on its own, so callers mint a new one
	// rather than persisting it.
	SignDownloadURL(ctx context.Context, key string) (*blobpb.DownloadUrl, error)
}

type Permission int

type Principal struct {
	Type PrincipalType
	ID   []byte
}

type PrincipalResolver interface {
	Covers(ctx context.Context, principal Principal, user *commonpb.UserId) (bool, error)
}

type PrincipalType int

type ProfileResolver struct{}

type RejectionMetadata struct {
	Reason RejectionReason

	// FlaggedCategory is the moderation category that tripped, set only when
	// Reason is RejectionReasonModeration; it is NONE (the zero value) otherwise.
	FlaggedCategory moderationpb.FlaggedCategory
}

type RejectionReason int

type RenditionRef struct {
	// ID is the child rendition blob's id — the same id GetBlobs resolves.
	ID *blobpb.BlobId

	// Rendition is which rendition role these bytes serve (display, thumbnail).
	Rendition RenditionType

	// MimeType is the rendition's own encoded type, which may differ from the
	// original's (e.g. an opaque PNG original yields JPEG renditions).
	MimeType string

	// SizeBytes is the size of the encoded rendition bytes.
	SizeBytes uint64

	// StorageKey is the object key the rendition's bytes live under, used to sign
	// its download URL. It never leaves the server.
	StorageKey string

	// Image is the rendition's derived image metadata — its own dimensions, and the
	// BlurHash copied from the original. Reuses the same type the original carries.
	Image *ImageMetadata
}

type RenditionType int

type Server struct {
	blobpb.UnimplementedBlobStorageServer
	// contains filtered or unexported fields
}

type State int

type Store interface {
	// CreatePending inserts a freshly reserved blob in the PENDING state. The
	// blob may be an ORIGINAL (nil ParentID) or a server-created rendition of an
	// existing original (ParentID set).
	//
	// ErrExists is returned if a blob with the same id already exists.
	CreatePending(ctx context.Context, blob *Blob) error

	// GetByID returns the blob with the given id, or ErrNotFound. Ownership is
	// not enforced here; callers that act on behalf of the uploader (e.g.
	// finalization) compare Owner themselves.
	GetByID(ctx context.Context, id *blobpb.BlobId) (*Blob, error)

	// GetByIDs returns the blobs among the given ids that exist, in unspecified
	// order. A BlobId is an opaque capability, so resolution is not scoped to an
	// owner; ids that do not exist are simply omitted. A BlobId resolves to at
	// most one record, so duplicate ids collapse to a single result. An original's
	// rendition manifest (Blob.Renditions) is included.
	GetByIDs(ctx context.Context, ids []*blobpb.BlobId) ([]*Blob, error)

	// AttachRenditions records an original's rendition manifest onto its own
	// record, so the whole set resolves in the single read that fetches the
	// original. It overwrites any manifest already present, so a replayed
	// generation that recomputes the same set is idempotent. It is only ever
	// called on an ORIGINAL, and refs may be empty (an original whose ladder
	// produced nothing).
	//
	// ErrNotFound is returned if no blob exists for the given id.
	AttachRenditions(ctx context.Context, id *blobpb.BlobId, refs []RenditionRef) error

	// Advance moves a blob forward along the success path to a later lifecycle
	// state, persisting derived metadata when provided (image is set only on the
	// transition into StateInspected). It advances strictly forward and never out
	// of a terminal state, so a replayed or concurrent finalize is idempotent:
	// advancing to a state the blob is already at or past is a no-op. The declared
	// MimeType and SizeBytes are never changed. Reaching StateReady also removes
	// the blob from the finalization queue, atomically with the transition.
	//
	// StateRejected is not a valid target — rejection is terminal and carries
	// metadata, so it is reached only through Reject. Passing it returns
	// ErrCannotAdvanceToRejected.
	//
	// It reports whether this call actually performed the transition. A false
	// return with a nil error means the blob was already at or past the target
	// (or terminal) — a concurrent or replayed finalize lost the race — so the
	// caller can stop instead of applying further side effects on a stale view.
	//
	// ErrNotFound is returned if no blob exists for the given id.
	Advance(ctx context.Context, id *blobpb.BlobId, to State, image *ImageMetadata) (bool, error)

	// Reject moves a non-terminal blob to the terminal StateRejected, recording
	// why. Like Advance it transitions only out of a non-terminal state and is
	// idempotent: it reports whether it performed the transition, and a false with
	// a nil error means the blob was already terminal — a concurrent or replayed
	// finalize won the race, so the committed rejection (or readiness) stands and
	// must not be overwritten. Rejection also removes the blob from the
	// finalization queue, atomically with the transition.
	//
	// ErrNotFound is returned if no blob exists for the given id.
	Reject(ctx context.Context, id *blobpb.BlobId, rejection *RejectionMetadata) (bool, error)

	// MarkForFinalization queues a blob on its content kind's finalization
	// queue, due at nextAttemptAt. It is idempotent: re-marking an already-queued
	// blob resets its due time (and moves it if the kind changed, though a blob's
	// kind never legitimately changes) but preserves its failed-attempt count,
	// and marking a blob that already reached a terminal state is a no-op (the
	// work is done, so nothing is queued).
	//
	// ErrNotFound is returned if no blob exists for the given id.
	MarkForFinalization(ctx context.Context, id *blobpb.BlobId, kind ContentKind, nextAttemptAt time.Time) error

	// GetDueForFinalization returns up to limit blobs queued under kind whose due
	// time is at or before asOf, soonest first.
	GetDueForFinalization(ctx context.Context, kind ContentKind, asOf time.Time, limit int) ([]*FinalizationTask, error)

	// GetFinalizationQueueStats reports kind's queue depth and the enqueue time
	// of its longest-queued blob, in one walk of the queue. It backs the queue
	// gauges: depth trending up faster than workers drain it means the queue is
	// growing, and a max age climbing while depth stays flat means something is
	// stuck retrying rather than merely busy.
	GetFinalizationQueueStats(ctx context.Context, kind ContentKind) (*FinalizationQueueStats, error)

	// ClaimForFinalization pushes a queued blob's due time out to until, provided
	// it is still queued and due as of asOf. It reports whether the claim was
	// performed: false means the blob left the queue (it reached a terminal
	// state) or is no longer due (another worker claimed or delayed it first).
	//
	// A claim is an efficiency guard, not a lock — finalization is idempotent and
	// safe to run concurrently; claiming only keeps workers from duplicating
	// expensive work (e.g. moderation calls). A crashed claimant needs no
	// recovery: the claim expires when its until passes and the task simply
	// becomes due again.
	ClaimForFinalization(ctx context.Context, id *blobpb.BlobId, asOf, until time.Time) (bool, error)

	// DelayFinalization reschedules a queued blob after a failed attempt: its due
	// time moves to nextAttemptAt and its failed-attempt count increments. It is
	// a no-op on a blob that is no longer queued (a concurrent finalize drove it
	// terminal, dequeuing it).
	DelayFinalization(ctx context.Context, id *blobpb.BlobId, nextAttemptAt time.Time) error
}

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

type WorkerOption func(*Worker)