Protected_The ID of the FileStorageAccount this driver instance is operating for. Set during initialization via the config parameter.
Protected_The name of the FileStorageAccount (for logging/display purposes).
Protected ReadonlyproviderThe name of this storage provider, used in error messages and logging. Each implementation must define this property with a descriptive name.
Gets the account ID this driver instance is operating for. Returns undefined if the driver was not initialized with an account.
Gets the account name this driver instance is operating for. Returns undefined if the driver was not initialized with an account.
True when a root directory is known (STORAGE_LOCAL_ROOT or rootPath).
Returns true if the storage provider driver supports generating pre-authenticated direct download URLs.
true if the driver supports pre-authenticated downloads; false otherwise.
Returns true if the storage provider driver supports generating pre-authenticated direct upload URLs.
When true, callers can invoke CreatePreAuthUploadUrl to get a direct cloud storage upload URL and send raw binary data directly to the storage service without routing through intermediate servers.
true if the driver supports pre-authenticated uploads; false otherwise.
Indicates whether this provider supports streaming/ranged downloads via GetObjectStream.
The base default is false. Streaming-capable drivers override this getter to
return true. Callers MUST check this getter before calling GetObjectStream,
or be ready to catch StreamingNotSupportedError.
true if the provider can serve ranged, streamed reads; false otherwise.
Copies a file under the root, creating the destination's directories. A symlink at either key is refused: the copy would read the file the source link points at, or write through the destination link into the file it points at.
Creates a directory under the root with any missing parents.
A file:// URL to the object, readable only by processes on this host.
Not supported: a local directory has no upload endpoint.
Deletes a directory below the root (the root itself is refused). Non-recursive removes only an empty directory —
a non-empty one surfaces the OS error (ENOTEMPTY); recursive removes the whole tree. A missing directory counts
as deleted either way.
Optionalrecursive: booleanDeletes a file under the root; a file that does not exist is already deleted (true).
Whether a directory exists under the root (the root included); a symlink is not a directory, so its key answers false.
Releases any resources (keep-alive sockets, connection pools, credential timers) held by
this driver's underlying SDK client. Called by FileStorageEngine before a cached
driver instance is dropped or replaced (e.g. RefreshDriverCache(), or the on-demand
GetDriver() fallback overwriting a stale entry) so the old client doesn't keep its socket
pool alive after nothing can reach it.
Default is a no-op: most storage SDKs used here (Azure, Box, Dropbox, Google) don't expose an explicit client-teardown API, so there is nothing safe to call. Drivers whose SDK client does expose one (see AWSFileStorage.Dispose) should override this.
Keys are paths here, so objectId and fullPath address the same thing; fullPath wins when both are given.
Keys are paths here, so objectId and fullPath address the same thing; fullPath wins when both are given.
contentType is always application/octet-stream: a plain file system stores no content type.
Streams an object's content (optionally a byte range) without buffering the whole object in memory.
Use this instead of GetObject when serving large media (audio/video) over
HTTP — pipe the returned ObjectStreamResult.Stream directly to the HTTP
response and propagate ContentType/ContentLength/ContentRange to the response
headers. GetObject returns the full object as a Buffer and is appropriate only for
small payloads you need fully in memory.
Range semantics: params.Range is an inclusive byte range
({ Start, End }), matching the HTTP Range/Content-Range model. Omit End to
stream from Start to EOF. When a range is honored, the result's ContentRange
carries the actual Start/End returned and the object's Total size — enough to
emit Content-Range: bytes Start-End/Total and a 206 Partial Content status. When
no Range is supplied, the whole object is streamed and ContentRange is omitted.
Capability gating: The base class provides a default implementation that throws
StreamingNotSupportedError. This means drivers that don't support streaming
inherit the throw automatically (no boilerplate stubs) and SupportsStreaming
stays false. Callers MUST therefore either check SupportsStreaming first, or be
prepared to catch StreamingNotSupportedError and fall back to GetObject.
Object identifier (prefer objectId, fall back to fullPath) plus an
optional inclusive Range.
A Promise resolving to an ObjectStreamResult with the readable stream and accompanying content metadata.
if (!storage.SupportsStreaming) {
// fall back to a full buffered read
}
const result = await storage.GetObjectStream({
objectId: 'media/big-video.mp4',
Range: { Start: 0, End: 1_048_575 }, // first 1 MiB, inclusive
});
res.status(result.ContentRange ? 206 : 200);
if (result.ContentType) res.setHeader('Content-Type', result.ContentType);
if (result.ContentLength != null) res.setHeader('Content-Length', String(result.ContentLength));
if (result.ContentRange) {
const { Start, End, Total } = result.ContentRange;
res.setHeader('Content-Range', `bytes ${Start}-${End}/${Total}`);
}
result.Stream.pipe(res);
Records the account (base behaviour) and, when the configuration carries a non-empty rootPath, uses it as the
root in place of STORAGE_LOCAL_ROOT.
Optionalconfig: StorageProviderConfigThe files and sub-directories directly under prefix ('' or '/' for the root), in ordinal name order (stable
and locale-independent). Symlinked entries are omitted; a symlinked prefix is refused.
Optional_delimiter: stringMoves (renames) a file under the root, creating the destination's directories; a symlink at either key is refused.
The canonical form of an object key for this storage — what the storage access checks compare when they ask whether
an object backs an MJ: Files row (see StorageAccessEvaluator.UnreadableTrackedObjectKeys). Both the key a client
sends and the key a row stores go through this one method, so two spellings this driver resolves to the same object
must canonicalize alike.
The default (NormalizeStorageObjectKey) trims the key, collapses runs of / and strips leading and
trailing / — right for every driver whose spellings differ only in slashes. A driver that adds its own root or
prefix to SOME keys and not others (S3's key prefix) overrides this to return the key relative to that root.
Case is preserved; callers compare case-insensitively.
An object key as a client or an MJ: Files row spells it
The canonical key: relative to this driver's root, no leading/trailing /, no repeated /
Whether a file exists under the root; a directory or a symlink is not an object, so its key answers false.
Writes the bytes atomically (a temporary file in the same directory, renamed over the key), creating parent directories; a symlink at the key is refused rather than replaced. The content type and metadata are not stored: a plain file system has nowhere to keep them.
Optional_contentType: stringOptional_metadata: Record<string, string>Not supported: a local directory has no search index.
ProtectedthrowHelper method to throw an UnsupportedOperationError with appropriate context. This method simplifies implementation of methods not supported by specific providers.
The name of the method that is not supported
A FileStorageBase driver over one directory of the server's file system.