ctx.files in mutations and operations.
Hierarchy
-
FilesReader↳FilesWriter
Methods
inspect
▸ inspect(file): Promise<FileInfo>
The metadata of a file, read through its locator. A protected file needs
the route it is read through (attachment(record, field)), decided as
delivery decides it, unless this transaction accepted it; its native row
and current source permissions are read dependencies, so an erasure
racing this transaction refuses its result or commit. Missing, erased
and unauthorized files, and a protected file named without a route,
throw FileUnavailable; an attachment whose field now names another
file throws FileAttachmentChanged. An ordinary file needs no route.
Parameters
Returns
Promise<FileInfo>
Inherited from
FilesReader.inspectisAvailable
▸ isAvailable(file): Promise<boolean>
Logical availability in this component’s file namespace, including all
ancestor erasure barriers. Reveals no metadata, permissions or byte
capability; it does not probe physical blob existence.
Parameters
Returns
Promise<boolean>
Inherited from
FilesReader.isAvailableerasure
▸ erasure(erasure): Promise<FileErasure | null>
The progress of an accepted erasure of this component’s file, read
from durable state, or null when the reference names none. Reveals no
digest, size, name or byte capability.
Parameters
Returns
Promise<FileErasure | null>
Inherited from
FilesReader.erasureinspectWorkloadGrant
▸ inspectWorkloadGrant(file, options): Promise<WorkloadGrantInfo>
This component’s live workload grant of a file under the exact key.
Current source permissions and erasure are read dependencies. Returns
no URL or secret and never renews a delivery; suitable for queries and
operation review.
Parameters
Returns
Promise<WorkloadGrantInfo>
Inherited from
FilesReader.inspectWorkloadGrantaccept
▸ accept(staged): Promise<FileRef>
Accept a staged file submitted to the current operation into its
declared destination: const file = await ctx.files.accept(source).
The file, its attachment and the operation’s other changes commit
together. The engine checks at commit that the staged file belongs to
this operation, input and destination, satisfies the declared bounds,
and that the resulting record attaches it; accepting a file and not
attaching it aborts the transaction. A failed transaction leaves the
staged file reusable until its staging deadline.
Parameters
Returns
Promise<FileRef>
prepareUpload
▸ prepareUpload<Operation>(options): Promise<PreparedUpload>
Prepare private, sealed staging for a declared operation file input.
Transfer verifies the bytes; Save accepts the staged file in its
ordinary business transaction. Upload selection and Save have separate
request keys, so unrelated form fields remain editable while bytes
arrive.
Type parameters
Parameters
Returns
Promise<PreparedUpload>
erase
▸ erase(file): Promise<FileErasure>
Erase exact protected content. The file owner’s disclosure rule must
explicitly permit storageErase; read, replace and grant rights do not
imply it. Detaching a relationship does not call erase. Requires every
current attachment and source owner’s erasure decision, and grants no
permission to read the file. An attachment locator must still resolve
to this exact file. A legal hold refuses it here, before acceptance;
once accepted, nothing reopens access.
Returns the accepted erasure request, fenced when this mutation
commits, not an assertion that its work has finished: read its progress
with erasure.
Parameters
Returns
Promise<FileErasure>
eraseAttachments
▸ eraseAttachments(record): Promise<void>
Erase the immutable attachment scope established when this record’s files
were uploaded, including detached copies and transitive derivatives.
The record’s disclosure rule must permit storageRecordErase. Legal
holds refuse it. Ordinary record deletion and detachment never call
this method. Key destruction resumes durably after the mutation closes
the scope.
Parameters
Returns
Promise<void>
grant
▸ grant(file, options): Promise<FileGrant>
Grant one recipient access to a protected file under current source
policy, until expires_at (epoch milliseconds). The recipient reads it
with the returned grant, itself a file locator. request_key makes a
retried grant return the grant it already issued.
Parameters
Returns
Promise<FileGrant>
revoke
▸ revoke(grant): Promise<void>
Revoke one grant: no new read is admitted through it. Other grants and
the stored bytes are unchanged.
Parameters
Returns
Promise<void>
grantWorkload
▸ grantWorkload(file, options): Promise<void>
Grant a workload this protected file’s exact bytes until expires_at
(at most MAX_WORKLOAD_GRANT_LIFETIME_MS ahead): this component’s own
work when holder is omitted, or an installed child (holder, e.g.
components.datasets, and key, e.g. a version id). Call it in the
mutation that admits the work: the file is read through the caller’s
current access (through its attachment, when a locator names one), and
the commit is a disclosure of those reads to the workload, which the
file’s sources must permit. Repeating a grant the key holds live keeps
it, and reads and discloses nothing. At most MAX_WORKLOAD_GRANTS per
holder key; past it the refusal is a BijectionError bound_exceeded
naming WORKLOAD_GRANTS_BOUND.
Parameters
Returns
Promise<void>
redeemWorkloadGrant
▸ redeemWorkloadGrant(file, options): Promise<WorkloadDelivery>
This component’s workload grant, as a holder, of a file another
component granted it under key, delivered to its worker: reads only
the grant and the file’s row, so it needs no identity. Only the holder
redeems: called from any other component it finds no grant. Refused
without a live grant. expires_at bounds this delivery in epoch
milliseconds, independently of the grant, which it never extends.
Parameters
Returns
Promise<WorkloadDelivery>
passWorkloadGrants
▸ passWorkloadGrants(from, to): Promise<number>
Pass every live workload grant this component holds under from to its
key to (a run’s grants to its follow-up run), with fresh credentials
and the same expiries; credentials issued under from stop working. A
file to already holds keeps that grant. Refused past
MAX_WORKLOAD_GRANTS under to (bound_exceeded). Returns the grants
to gained.
Parameters
Returns
Promise<number>
endWorkloadGrants
▸ endWorkloadGrants(key, options?): Promise<number>
End the workload grants this component holds under key (its run
settled or was cancelled), or with until shorten them to end by then
(its deadline). Never extends a grant. Returns the grants changed.
Parameters
Returns
Promise<number>