files

type AttachRequest struct {
	TenantID uuid.UUID
	Upload   Upload

	// Owner is the row the file hangs off. Its identifier is zero for a file
	// being uploaded as part of the create that will hold it — see
	// [Service.Prepare].
	Owner Owner

	// URL builds the download path once the file has an identifier and a name.
	// The endpoint's own route is what it renders, which is why a generator
	// supplies it rather than this package guessing.
	URL func(fileID uuid.UUID, name string) string
}

type Config struct {
	// Store is where the bytes go.
	Store blob.Store
	// DB is the pool the owning tables are in. The same one, deliberately: the
	// transaction that finalizes a file and writes its owner has to be one
	// transaction, and it cannot be if the two live in different pools.
	DB DB

	// MaxBytes caps one upload. Zero means [DefaultMaxBytes].
	MaxBytes int64
	// InlineTypes are the sniffed types served without an attachment
	// disposition. Nil means [DefaultInlineTypes]; an explicitly empty slice
	// means everything downloads.
	InlineTypes []string

	// AbandonedAfter and RestoreWindow are the sweeper's two rules. Zero means
	// the defaults.
	AbandonedAfter time.Duration
	RestoreWindow  time.Duration

	// Now is the clock, so a test can move it. Nil means time.Now.
	Now func() time.Time

	// Logger is where [Service.Sweep] says what it reaped.
	//
	// Nil is not silence: it is [log/slog.Default], the reading every other
	// Logger in rig gives it. [SweepReport] exists for "the log line the task
	// writes" and the generated task discards it, so what a project's
	// housekeeping actually did has never been written anywhere.
	//
	// The line is INFO, unlike the per-interval lines rig's two background
	// loops write. Nothing sweeps files in-process — [Service.Sweep] is reached
	// from the generated `sweep-files` cron job and nowhere else — so this is
	// the whole output of a run that happens when nobody is watching, and
	// [log/slog.Default] drops DEBUG. A level that has to have been turned on
	// in advance would leave a sweep that did nothing looking exactly like a
	// cron entry that never fired.
	//
	// A sweep that failed is not logged here at all: the error is returned, and
	// whatever ran the task reports it once.
	Logger *slog.Logger
}

type Content struct {
	File *File
	Body io.ReadSeekCloser
}

type DB = dbx.Pool

type File struct {
	ID       uuid.UUID
	TenantID uuid.UUID

	StorageKey string
	// URL is where the file is served from — the download route, with the
	// identifier and the name in it. Stable and unsigned, so holding it grants
	// nothing and the endpoint behind it still authorizes.
	URL string

	Name string
	// ContentType is what the bytes were sniffed to be, which is what a download
	// announces.
	ContentType string
	// DeclaredType is what the client claimed, kept beside the sniffed type
	// rather than instead of it.
	DeclaredType string

	Size     int64
	Checksum string

	CreatedAt  time.Time
	UploadedAt *time.Time
	DeletedAt  *time.Time
}

type Owner struct {
	Table string
	// IDColumn is the owning table's primary key, normally "id".
	IDColumn string
	// TenantColumn scopes the update. Empty for a table with no tenant column,
	// which is not a shape rig generates but is one a test can build.
	TenantColumn string
	// FileColumn is the `<role>_file_id` column the identifier is written to.
	FileColumn string

	ID uuid.UUID

	// Forget withdraws whatever is being held of this row, and it exists because
	// this is the one place rig writes an application's table from outside that
	// table's generated repository.
	//
	// A table that holds its rows between requests is invalidated by the writes
	// its repository makes, and the statement below is not one of them: attaching
	// a file changes the row's `<role>_file_id` and every replica holding it would
	// go on saying there is no file there — which the download endpoint answers as
	// a 404, for a file that was just uploaded successfully.
	//
	// Generated code fills this in for a table that asked to be held, and it is
	// called inside the transaction that writes the column, so the withdrawal is
	// atomic with the change and discarded by a rollback. Nil is the ordinary
	// case and means nothing is held.
	Forget func(ctx context.Context) error
}

type Pending struct {
	File *File
	// Part is the form part this came from, so a generated create can put each
	// identifier on the right column.
	Part string
}

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

type SweepReport struct {
	// Abandoned is the number of rows reaped because their bytes never arrived.
	Abandoned int
	// Expired is the number reaped because their restore window closed.
	Expired int
	// Remarked is the number of deleted objects the bucket had not been told
	// about, brought back into step.
	Remarked int
}

type Upload struct {
	// Name is what the file is called. It goes on the row and into the download
	// path, and it never becomes the storage key: see [blob.Key].
	Name string
	// DeclaredType is the type the client claimed. It is recorded and then
	// largely ignored — the sniffed type is the one that is stored and served.
	DeclaredType string
	Body         io.Reader
}