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

	// 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 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
}

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)

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

	// 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 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 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.
	GetByIDs(ctx context.Context, ids []*blobpb.BlobId) ([]*Blob, error)

	// GetRenditions returns every blob whose ParentID is parentID — i.e. all
	// server-derived renditions of the given original — in unspecified order. It
	// returns an empty slice (not ErrNotFound) when there are none.
	GetRenditions(ctx context.Context, parentID *blobpb.BlobId) ([]*Blob, 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.
	//
	// 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.
	//
	// ErrNotFound is returned if no blob exists for the given id.
	Reject(ctx context.Context, id *blobpb.BlobId, rejection *RejectionMetadata) (bool, error)
}