@stacksjs/storage 0.75.548 → 0.75.552
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +47 -0
- package/dist/adapters/bun.js +1 -1
- package/dist/adapters/local.js +1 -1
- package/dist/filesystem-common.d.ts +16 -0
- package/dist/filesystem-common.js +1 -1
- package/dist/move.d.ts +16 -0
- package/dist/move.js +3 -2
- package/package.json +11 -11
package/README.md
CHANGED
|
@@ -61,6 +61,53 @@ expiry has passed. A bare signature has no known expiry. When capacity is full,
|
|
|
61
61
|
revocation throws explicitly and preserves existing revocations; rotate
|
|
62
62
|
`APP_KEY` or supply a durable application revocation store before retrying.
|
|
63
63
|
|
|
64
|
+
## Recoverable local rename
|
|
65
|
+
|
|
66
|
+
`rename` and `move` return a Result. Inspect an error result before using the
|
|
67
|
+
destination:
|
|
68
|
+
|
|
69
|
+
```ts
|
|
70
|
+
import { rename, StorageRenameRecoveryError } from '@stacksjs/storage/move'
|
|
71
|
+
|
|
72
|
+
const result = await rename(preparedDirectory, outputDirectory, { overwrite: true })
|
|
73
|
+
if (result.isErr) {
|
|
74
|
+
if (result.error instanceof StorageRenameRecoveryError)
|
|
75
|
+
console.error(result.error.phase, result.error.lock, result.error.backup)
|
|
76
|
+
throw result.error
|
|
77
|
+
}
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Overlapping source/destination trees are rejected, including existing parent
|
|
81
|
+
aliases. Ordinary files and empty directories use native rename directly. If
|
|
82
|
+
the OS refuses a directory/type replacement, the existing destination moves
|
|
83
|
+
into an owned sibling backup before installation. Installation failure restores
|
|
84
|
+
the previous entry and returns the original error. Successful replacement
|
|
85
|
+
replaces the entire entry, so stale output files do not survive.
|
|
86
|
+
|
|
87
|
+
An exclusive destination lock serializes cooperating callers. Existing locks
|
|
88
|
+
fail closed, including those retained after interruption. Common case/Unicode
|
|
89
|
+
aliases share a conservative lock; distinct case-sensitive names can therefore
|
|
90
|
+
contend. `StorageRenameRecoveryError` has `code`, `source`, `destination`, `lock`,
|
|
91
|
+
`backup`, `phase`, `installed`, `cause` and optional `recoveryError` fields. A
|
|
92
|
+
rollback or cleanup failure preserves remaining backup/lock state for inspection.
|
|
93
|
+
`installed: true` means installation completed before cleanup failed; it does
|
|
94
|
+
not mean rollback occurred. A lock error may also mean that the lock could not
|
|
95
|
+
be created, as identified by its original filesystem cause.
|
|
96
|
+
|
|
97
|
+
The private lock's `operation.json` records planned paths and entry identities.
|
|
98
|
+
After process interruption, stop the operation's owner and inspect those paths
|
|
99
|
+
and actual payloads before recovery. The record is diagnostic state, not an
|
|
100
|
+
authorization to delete a directory, and age alone never authorizes cleanup.
|
|
101
|
+
The function does not automatically resume an interrupted operation.
|
|
102
|
+
|
|
103
|
+
Callers authorize and control source/destination parents and validate their
|
|
104
|
+
content before replacement. Operations are synchronous inside the async Result
|
|
105
|
+
API. The two-step directory path has a temporary missing-destination window.
|
|
106
|
+
The lock and identity checks coordinate this API's callers; they do not sandbox
|
|
107
|
+
hostile same-user replacement, provide content authentication, or establish
|
|
108
|
+
hardware power-loss durability. Prepared-artifact publication below retains its
|
|
109
|
+
separate new-directory completion contract.
|
|
110
|
+
|
|
64
111
|
## Bounded local text reads
|
|
65
112
|
|
|
66
113
|
Use the standalone entrypoint for local text supplied by a user or worker:
|
package/dist/adapters/bun.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
import{localDirectoryPage}from"../directory-page";import{Buffer}from"node:buffer";import{file,write as bunWrite}from"bun";import{chmod,copyFile,lstat,mkdir,rename,rm,unlink}from"node:fs/promises";import{dirname,join,relative}from"node:path";import{createDirectoryListing}from"../types";import{createSignedStorageToken}from"../signed-url";import{publicUrlFor,resolveStoragePath,signedUrlBase,writeAtomically}from"../filesystem-common";export class BunStorageAdapter{root;url;disk;constructor(config={}){this.root=config.root||process.cwd();this.url=config.url;this.disk=config.disk}resolvePath(path){return resolveStoragePath(this.root,path)}async write(path,contents){const fullPath=this.resolvePath(path);if(!(typeof contents==="string"||contents instanceof Uint8Array)){const stream=contents;if(typeof stream.getReader!=="function"){throw new TypeError("[storage/bun] contents must be a web-standard ReadableStream "+"(with .getReader()), not a Node stream.Readable. "+"Convert via Readable.toWeb(nodeStream) before passing.")}}await writeAtomically(fullPath,async(temporary)=>{if(typeof contents==="string"||contents instanceof Uint8Array)await bunWrite(temporary,contents);else await
|
|
1
|
+
import{localDirectoryPage}from"../directory-page";import{Buffer}from"node:buffer";import{file,write as bunWrite}from"bun";import{chmod,copyFile,lstat,mkdir,rename,rm,unlink}from"node:fs/promises";import{dirname,join,relative}from"node:path";import{createDirectoryListing}from"../types";import{createSignedStorageToken}from"../signed-url";import{publicUrlFor,resolveStoragePath,signedUrlBase,writeAtomically,writeStreamToFile}from"../filesystem-common";export class BunStorageAdapter{root;url;disk;constructor(config={}){this.root=config.root||process.cwd();this.url=config.url;this.disk=config.disk}resolvePath(path){return resolveStoragePath(this.root,path)}async write(path,contents){const fullPath=this.resolvePath(path);if(!(typeof contents==="string"||contents instanceof Uint8Array)){const stream=contents;if(typeof stream.getReader!=="function"){throw new TypeError("[storage/bun] contents must be a web-standard ReadableStream "+"(with .getReader()), not a Node stream.Readable. "+"Convert via Readable.toWeb(nodeStream) before passing.")}}await writeAtomically(fullPath,async(temporary)=>{if(typeof contents==="string"||contents instanceof Uint8Array)await bunWrite(temporary,contents);else await writeStreamToFile(temporary,contents)});const written=file(fullPath);return{path,size:written.size,lastModified:written.lastModified}}async read(path){const fullPath=this.resolvePath(path);const bunFile=file(fullPath);if(!await bunFile.exists()){throw new Error(`File not found: ${path}`)}return await bunFile.arrayBuffer().then((buf)=>new Uint8Array(buf))}async getStream(path,_options){const fullPath=this.resolvePath(path);const bunFile=file(fullPath);if(!await bunFile.exists())throw new Error(`File not found: ${path}`);return bunFile.stream()}async putStream(path,stream,options){const fullPath=this.resolvePath(path);const signal=options?.signal;signal?.throwIfAborted();await writeAtomically(fullPath,async(temporary)=>{await writeStreamToFile(temporary,stream,signal)});const written=file(fullPath);return{path,size:written.size,contentType:options?.contentType,lastModified:written.lastModified}}async readToString(path){const fullPath=this.resolvePath(path);const bunFile=file(fullPath);if(!await bunFile.exists()){throw new Error(`File not found: ${path}`)}return await bunFile.text()}async readToBuffer(path){const fullPath=this.resolvePath(path);const bunFile=file(fullPath);if(!await bunFile.exists()){throw new Error(`File not found: ${path}`)}const arrayBuffer=await bunFile.arrayBuffer();return Buffer.from(arrayBuffer)}async readToUint8Array(path){const fullPath=this.resolvePath(path);const bunFile=file(fullPath);if(!await bunFile.exists()){throw new Error(`File not found: ${path}`)}const arrayBuffer=await bunFile.arrayBuffer();return new Uint8Array(arrayBuffer)}async deleteFile(path){const fullPath=this.resolvePath(path);await unlink(fullPath).catch((error)=>{if(error.code!=="ENOENT")throw error})}async deleteDirectory(path){const fullPath=this.resolvePath(path);await rm(fullPath,{recursive:true,force:true})}async createDirectory(path){const fullPath=this.resolvePath(path);await mkdir(fullPath,{recursive:true})}async moveFile(from,to){const fromPath=this.resolvePath(from);const toPath=this.resolvePath(to);await mkdir(dirname(toPath),{recursive:true});await rename(fromPath,toPath)}async copyFile(from,to){const fromPath=this.resolvePath(from);const toPath=this.resolvePath(to);await mkdir(dirname(toPath),{recursive:true});await copyFile(fromPath,toPath)}async stat(path){const fullPath=this.resolvePath(path);const bunFile=file(fullPath);if(!await bunFile.exists()){throw new Error(`File not found: ${path}`)}const stats=await Bun.file(fullPath).stat();const isDir=stats.isDirectory();return{path,type:isDir?"directory":"file",visibility:await this.visibility(path),size:isDir?0:stats.size,lastModified:stats.mtime?.getTime()||Date.now(),mimeType:isDir?undefined:bunFile.type}}listPage(path,options={}){return localDirectoryPage(this.resolvePath(path),path,options)}list(path,options={}){const fullPath=this.resolvePath(path);return this.createAsyncIterator(fullPath,options.deep||false)}async*createAsyncIterator(dirPath,deep){const entries=[];try{const glob=new Bun.Glob(deep?"**/*":"*");for await(const entry of glob.scan({cwd:dirPath,onlyFiles:false})){const fullEntryPath=join(dirPath,entry);const stats=await Bun.file(fullEntryPath).stat();entries.push({path:relative(this.root,fullEntryPath),type:stats.isDirectory()?"directory":"file"})}}catch(error){return}yield*createDirectoryListing(entries)}async changeVisibility(path,vis){const fullPath=this.resolvePath(path);const stats=await lstat(fullPath);const isDir=stats.isDirectory();const mode=vis==="public"?isDir?493:420:isDir?448:384;await chmod(fullPath,mode)}async visibility(path){const fullPath=this.resolvePath(path);const stats=await lstat(fullPath);const perms=stats.mode&511;return perms&4?"public":"private"}async fileExists(path){const fullPath=this.resolvePath(path);const bunFile=file(fullPath);return await bunFile.exists()}async directoryExists(path){const fullPath=this.resolvePath(path);try{const stats=await Bun.file(fullPath).stat();return stats.isDirectory()}catch{return false}}async publicUrl(path,options={}){return publicUrlFor(path,{domain:options.domain,diskUrl:this.url})}async temporaryUrl(path,options){return await this.signedUrl(path,{expiresIn:options.expiresIn})}async signedUrl(path,options){const token=createSignedStorageToken(path,{...options,disk:options.disk??this.disk});return`${signedUrlBase(options.baseUrl)}/__storage/${encodeURIComponent(path)}?token=${token}`}async checksum(path,options={}){const algorithm=options.algorithm||"sha256";const fullPath=this.resolvePath(path);const bunFile=file(fullPath);if(!await bunFile.exists()){throw new Error(`File not found: ${path}`)}const hasher=new Bun.CryptoHasher(algorithm);const arrayBuffer=await bunFile.arrayBuffer();hasher.update(new Uint8Array(arrayBuffer));return hasher.digest("hex")}async mimeType(path,_options={}){const fullPath=this.resolvePath(path);const bunFile=file(fullPath);if(!await bunFile.exists()){throw new Error(`File not found: ${path}`)}return bunFile.type||"application/octet-stream"}async lastModified(path){const stats=await this.stat(path);return stats.lastModified}async fileSize(path){const stats=await this.stat(path);return stats.size}}export function createBunStorage(config={}){return new BunStorageAdapter(config)}
|
package/dist/adapters/local.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
import{localDirectoryPage}from"../directory-page";import{Buffer}from"node:buffer";import{createReadStream
|
|
1
|
+
import{localDirectoryPage}from"../directory-page";import{Buffer}from"node:buffer";import{createReadStream}from"node:fs";import{access,chmod,constants,copyFile,lstat,mkdir,readdir,readFile,rename,rm,stat,unlink,writeFile}from"node:fs/promises";import{basename,dirname,join,relative}from"node:path";import{Readable}from"node:stream";import{createDirectoryListing}from"../types";import{createSignedStorageToken}from"../signed-url";import{publicUrlFor,resolveStoragePath,signedUrlBase,writeAtomically,writeStreamToFile}from"../filesystem-common";export class LocalStorageAdapter{root;url;disk;constructor(config={}){this.root=config.root||process.cwd();this.url=config.url;this.disk=config.disk}resolvePath(path){return resolveStoragePath(this.root,path)}async write(path,contents){const fullPath=this.resolvePath(path);await writeAtomically(fullPath,async(temporary)=>{if(typeof contents==="string"){await writeFile(temporary,contents,"utf8")}else if(contents instanceof Uint8Array){await writeFile(temporary,contents)}else{await writeStreamToFile(temporary,contents)}});const st=await stat(fullPath);return{path,size:st.size,lastModified:st.mtimeMs}}async read(path){const fullPath=this.resolvePath(path);return await readFile(fullPath)}async getStream(path,options){const fullPath=this.resolvePath(path);await access(fullPath,constants.R_OK);const nodeStream=createReadStream(fullPath,{signal:options?.signal});return Readable.toWeb(nodeStream)}async putStream(path,stream,options){const fullPath=this.resolvePath(path);await writeAtomically(fullPath,async(temporary)=>{await writeStreamToFile(temporary,stream,options?.signal)});const st=await stat(fullPath);return{path,size:st.size,contentType:options?.contentType,lastModified:st.mtimeMs}}async readToString(path){const fullPath=this.resolvePath(path);return await readFile(fullPath,"utf8")}async readToBuffer(path){const fullPath=this.resolvePath(path);return await readFile(fullPath)}async readToUint8Array(path){const fullPath=this.resolvePath(path);const buffer=await readFile(fullPath);return new Uint8Array(buffer)}async deleteFile(path){const fullPath=this.resolvePath(path);await unlink(fullPath).catch((error)=>{if(error.code!=="ENOENT")throw error})}async deleteDirectory(path){const fullPath=this.resolvePath(path);await rm(fullPath,{recursive:true,force:true})}async createDirectory(path){const fullPath=this.resolvePath(path);await mkdir(fullPath,{recursive:true})}async moveFile(from,to){const fromPath=this.resolvePath(from);const toPath=this.resolvePath(to);const toDir=dirname(toPath);await mkdir(toDir,{recursive:true});await rename(fromPath,toPath)}async copyFile(from,to){const fromPath=this.resolvePath(from);const toPath=this.resolvePath(to);const toDir=dirname(toPath);await mkdir(toDir,{recursive:true});await copyFile(fromPath,toPath)}async stat(path){const fullPath=this.resolvePath(path);const stats=await lstat(fullPath);return{path,type:stats.isDirectory()?"directory":"file",visibility:await this.visibility(path),size:stats.size,lastModified:stats.mtimeMs,mimeType:stats.isFile()?await this.detectMimeType(fullPath):undefined}}listPage(path,options={}){return localDirectoryPage(this.resolvePath(path),path,options)}list(path,options={}){return this.createAsyncIterator(path,options.deep||false)}async*createAsyncIterator(path,deep){const fullPath=this.resolvePath(path);try{await access(fullPath,constants.R_OK)}catch{return}const entries=await this.readDirectoryRecursive(fullPath,deep);yield*createDirectoryListing(entries)}async readDirectoryRecursive(dirPath,deep){const entries=[];try{const items=await readdir(dirPath,{withFileTypes:true});for(const item of items){const itemPath=join(dirPath,item.name);const relativePath=relative(this.root,itemPath);entries.push({path:relativePath,type:item.isDirectory()?"directory":"file"});if(deep&&item.isDirectory()){const subEntries=await this.readDirectoryRecursive(itemPath,true);entries.push(...subEntries)}}}catch(error){if(error?.code!=="EACCES"&&error?.code!=="EPERM"){throw error}}return entries}async changeVisibility(path,vis){const fullPath=this.resolvePath(path);const stats=await lstat(fullPath);const isDir=stats.isDirectory();const mode=vis==="public"?isDir?493:420:isDir?448:384;await chmod(fullPath,mode)}async visibility(path){const fullPath=this.resolvePath(path);const stats=await lstat(fullPath);const perms=stats.mode&511;return perms&4?"public":"private"}async fileExists(path){const fullPath=this.resolvePath(path);try{const stats=await lstat(fullPath);return stats.isFile()}catch{return false}}async directoryExists(path){const fullPath=this.resolvePath(path);try{const stats=await lstat(fullPath);return stats.isDirectory()}catch{return false}}async publicUrl(path,options={}){return publicUrlFor(path,{domain:options.domain,diskUrl:this.url})}async temporaryUrl(path,options){return await this.signedUrl(path,{expiresIn:options.expiresIn})}async signedUrl(path,options){const token=createSignedStorageToken(path,{...options,disk:options.disk??this.disk});return`${signedUrlBase(options.baseUrl)}/__storage/${encodeURIComponent(path)}?token=${token}`}async checksum(path,options={}){const algorithm=options.algorithm||"sha256";const fullPath=this.resolvePath(path);const content=await readFile(fullPath);const hasher=new Bun.CryptoHasher(algorithm);hasher.update(content);return hasher.digest("hex")}async mimeType(path,options={}){const fullPath=this.resolvePath(path);return await this.detectMimeType(fullPath)}async detectMimeType(filePath){const ext=basename(filePath).split(".").pop()?.toLowerCase();const mimeTypes={txt:"text/plain",html:"text/html",css:"text/css",js:"application/javascript",json:"application/json",xml:"application/xml",pdf:"application/pdf",zip:"application/zip",jpg:"image/jpeg",jpeg:"image/jpeg",png:"image/png",gif:"image/gif",svg:"image/svg+xml",mp4:"video/mp4",mp3:"audio/mpeg",wav:"audio/wav"};return mimeTypes[ext||""]||"application/octet-stream"}async lastModified(path){const stats=await this.stat(path);return stats.lastModified}async fileSize(path){const stats=await this.stat(path);return stats.size}}export function createLocalStorage(config={}){return new LocalStorageAdapter(config)}
|
|
@@ -19,6 +19,22 @@ export declare function resolveStoragePath(root: string, path: string): string;
|
|
|
19
19
|
* over, so a private file stays private.
|
|
20
20
|
*/
|
|
21
21
|
export declare function writeAtomically(fullPath: string, write: (temporary: string) => Promise<void>): Promise<void>;
|
|
22
|
+
/**
|
|
23
|
+
* Write a web stream to `path`, a chunk at a time.
|
|
24
|
+
*
|
|
25
|
+
* A plain read-and-write loop, because neither shortcut survives Bun 1.3.
|
|
26
|
+
* `Bun.write(path, new Response(stream))`, which the Bun adapter used, never
|
|
27
|
+
* resolves there for any stream of any size, so an upload hung the request
|
|
28
|
+
* that made it. Node's `pipeline(Readable.fromWeb(stream), ...)`, which the
|
|
29
|
+
* local adapter used, completes but never rejects when the stream errors, so
|
|
30
|
+
* a failed upload hung instead of failing. Each write is awaited before the
|
|
31
|
+
* next read, which is all the backpressure there is to get wrong: a 512 MB
|
|
32
|
+
* stream peaks under 60 MB resident on Bun 1.3.0, 1.3.14 and 1.4.4.
|
|
33
|
+
*
|
|
34
|
+
* `signal` aborts the copy, between chunks or while waiting for one, and
|
|
35
|
+
* rejects with the signal's reason. The caller owns removing the partial file.
|
|
36
|
+
*/
|
|
37
|
+
export declare function writeStreamToFile(path: string, stream: ReadableStream<Uint8Array>, signal?: AbortSignal): Promise<void>;
|
|
22
38
|
/**
|
|
23
39
|
* Percent-encode each segment of a storage path, keeping its slashes: a file
|
|
24
40
|
* called `my photo #1.jpg` becomes `my%20photo%20%231.jpg`. Unencoded, the
|
|
@@ -1 +1 @@
|
|
|
1
|
-
import{randomBytes}from"node:crypto";import{lstatSync}from"node:fs";import{chmod,mkdir,rename,rm,stat}from"node:fs/promises";import{basename,dirname,isAbsolute,join,relative,resolve,sep}from"node:path";import process from"node:process";export function resolveStoragePath(root,path){const base=resolve(root);const target=join(base,path);const rel=relative(base,target);if(rel===".."||rel.startsWith(`..${sep}`)||isAbsolute(rel))throw new Error(`Path traversal detected: '${path}' resolves outside storage root`);let current=base;for(const segment of rel.split(sep).filter(Boolean)){current=join(current,segment);try{if(lstatSync(current).isSymbolicLink())throw new Error(`Storage path '${path}' contains a symlink`)}catch(error){if(error.code==="ENOENT")break;throw error}}return target}export async function writeAtomically(fullPath,write){await mkdir(dirname(fullPath),{recursive:true});const temporary=join(dirname(fullPath),`.${basename(fullPath)}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);try{await write(temporary);const previous=await stat(fullPath).catch(()=>null);if(previous)await chmod(temporary,previous.mode&4095);await rename(temporary,fullPath)}catch(error){await rm(temporary,{force:true}).catch(()=>{});throw error}}export function encodeStoragePath(path){return path.split("/").map((segment)=>encodeURIComponent(segment)).join("/")}export function publicUrlFor(path,options){const base=withScheme(options.domain??options.diskUrl??process.env.APP_URL??"http://localhost");return`${base.replace(/\/+$/,"")}/${encodeStoragePath(path.replace(/^\/+/,""))}`}export function signedUrlBase(baseUrl){return withScheme(baseUrl||process.env.APP_URL||"http://localhost").replace(/\/+$/,"")}function withScheme(base){if(base===""||base.startsWith("/")||/^[a-z][a-z0-9+.-]*:\/\//i.test(base))return base;return`https://${base}`}
|
|
1
|
+
import{randomBytes}from"node:crypto";import{lstatSync}from"node:fs";import{chmod,mkdir,open,rename,rm,stat}from"node:fs/promises";import{basename,dirname,isAbsolute,join,relative,resolve,sep}from"node:path";import process from"node:process";export function resolveStoragePath(root,path){const base=resolve(root);const target=join(base,path);const rel=relative(base,target);if(rel===".."||rel.startsWith(`..${sep}`)||isAbsolute(rel))throw new Error(`Path traversal detected: '${path}' resolves outside storage root`);let current=base;for(const segment of rel.split(sep).filter(Boolean)){current=join(current,segment);try{if(lstatSync(current).isSymbolicLink())throw new Error(`Storage path '${path}' contains a symlink`)}catch(error){if(error.code==="ENOENT")break;throw error}}return target}export async function writeAtomically(fullPath,write){await mkdir(dirname(fullPath),{recursive:true});const temporary=join(dirname(fullPath),`.${basename(fullPath)}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);try{await write(temporary);const previous=await stat(fullPath).catch(()=>null);if(previous)await chmod(temporary,previous.mode&4095);await rename(temporary,fullPath)}catch(error){await rm(temporary,{force:true}).catch(()=>{});throw error}}export async function writeStreamToFile(path,stream,signal){signal?.throwIfAborted();let stop;const aborted=signal&&new Promise((_resolve,reject)=>{stop=()=>reject(signal.reason??new DOMException("The operation was aborted.","AbortError"));signal.addEventListener("abort",stop,{once:true})});aborted?.catch(()=>{});const reader=stream.getReader();const handle=await open(path,"w");try{for(;;){const next=await(aborted?Promise.race([reader.read(),aborted]):reader.read());if(next.done)break;for(let offset=0;offset<next.value.length;)offset+=(await handle.write(next.value,offset)).bytesWritten}}catch(error){reader.cancel(error).catch(()=>{});throw error}finally{if(stop)signal?.removeEventListener("abort",stop);await handle.close()}}export function encodeStoragePath(path){return path.split("/").map((segment)=>encodeURIComponent(segment)).join("/")}export function publicUrlFor(path,options){const base=withScheme(options.domain??options.diskUrl??process.env.APP_URL??"http://localhost");return`${base.replace(/\/+$/,"")}/${encodeStoragePath(path.replace(/^\/+/,""))}`}export function signedUrlBase(baseUrl){return withScheme(baseUrl||process.env.APP_URL||"http://localhost").replace(/\/+$/,"")}function withScheme(base){if(base===""||base.startsWith("/")||/^[a-z][a-z0-9+.-]*:\/\//i.test(base))return base;return`https://${base}`}
|
package/dist/move.d.ts
CHANGED
|
@@ -11,9 +11,25 @@ export declare function move(src: string | string[], dest: string, options?: Mov
|
|
|
11
11
|
* Renaming a file onto itself is a no-op, or a change of case on a
|
|
12
12
|
* case-insensitive disk. With `overwrite` it used to delete the destination
|
|
13
13
|
* first, which was the source: the file was gone before the rename ran.
|
|
14
|
+
* Overwrite now keeps native replacement where supported and restores a
|
|
15
|
+
* directory backup after failed installation. Recovery errors preserve state
|
|
16
|
+
* for inspection; the two-step directory path has no atomic visibility claim.
|
|
14
17
|
*/
|
|
15
18
|
export declare function rename(from: string, to: string, options?: MoveOptions): Promise<Result<{ message: string }, Error>>;
|
|
16
19
|
declare interface MoveOptions {
|
|
17
20
|
overwrite?: boolean
|
|
18
21
|
}
|
|
22
|
+
/** A preserved replacement needs inspection before this destination is reused. */
|
|
23
|
+
export declare class StorageRenameRecoveryError extends Error {
|
|
24
|
+
/** @defaultValue 'ERR_STORAGE_RENAME_RECOVERY' */
|
|
25
|
+
readonly code: string;
|
|
26
|
+
readonly source: string;
|
|
27
|
+
readonly destination: string;
|
|
28
|
+
readonly lock: string;
|
|
29
|
+
readonly backup: string | undefined;
|
|
30
|
+
readonly phase: 'lock' | 'rollback' | 'cleanup';
|
|
31
|
+
readonly installed: boolean;
|
|
32
|
+
readonly recoveryError?: unknown;
|
|
33
|
+
constructor(source: string, destination: string, lock: string, backup: string | undefined, phase: 'lock' | 'rollback' | 'cleanup', installed: boolean, cause: unknown, recoveryError?: unknown);
|
|
34
|
+
}
|
|
19
35
|
export {};
|
package/dist/move.js
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
-
import{err,handleError,ok}from"@stacksjs/error-handling";import{log}from"@stacksjs/logging";import{path}from"@stacksjs/path";import{fs}from"./fs";export async function move(src,dest,options){try{if(Array.isArray(src)){const errors=[];const operations=src.map(async(file)=>{const from=file;const to=path.resolve(dest,path.basename(file));const result=await rename(from,to,options);if(result.isErr){log.error(result.error);errors.push(result.error)}});await Promise.all(operations);if(errors.length>0)return err(
|
|
1
|
+
import{createHash}from"node:crypto";import{isAbsolute,relative,sep}from"node:path";import{err,handleError,ok}from"@stacksjs/error-handling";import{log}from"@stacksjs/logging";import{path}from"@stacksjs/path";import{fs}from"./fs";export class StorageRenameRecoveryError extends Error{source;destination;lock;backup;phase;installed;recoveryError;code="ERR_STORAGE_RENAME_RECOVERY";constructor(source,destination,lock,backup,phase,installed,cause,recoveryError){super(`Storage rename ${phase} requires inspection at ${lock}${backup?`; previous entry: ${backup}`:""}`,{cause});this.source=source;this.destination=destination;this.lock=lock;this.backup=backup;this.phase=phase;this.installed=installed;this.recoveryError=recoveryError;this.name="StorageRenameRecoveryError"}}export async function move(src,dest,options){try{if(Array.isArray(src)){const errors=[];const operations=src.map(async(file)=>{const from=file;const to=path.resolve(dest,path.basename(file));const result=await rename(from,to,options);if(result.isErr){log.error(result.error);errors.push(result.error)}});await Promise.all(operations);if(errors.length>0)return err(errors[0]);return ok({message:"Files moved successfully"})}const from=src;const to=dest;const result=await rename(from,to,options);if(result.isErr){log.error(result.error);return err(result.error)}return ok({message:"File moved successfully"})}catch(error){return err(handleError(error))}}export async function rename(from,to,options){try{if(!fs.existsSync(from))return err(new Error(`File or directory does not exist: ${from}`));const source=canonicalEntry(from),destination=canonicalEntry(to);const sourceIdentity=identity(source),destinationIdentity=identity(destination);const sameEntry=source===destination||matches(sourceIdentity,destinationIdentity);if(!sameEntry){if(beneath(source,destination)||beneath(destination,source)||directoryContainsEntry(sourceIdentity,destination)||directoryContainsEntry(destinationIdentity,source))return err(new Error("Source and destination must not overlap"))}const dir=path.dirname(to);if(!fs.existsSync(dir))fs.mkdirSync(dir,{recursive:true});if(canonicalEntry(from)!==source||canonicalEntry(to)!==destination)throw new Error("The source or destination parent changed");replaceEntry(source,destination,options?.overwrite===true);return ok({message:"File moved successfully"})}catch(error){if(error?.code==="ENOENT")log.error(`File or directory does not exist
|
|
2
2
|
|
|
3
|
-
`,error);else log.error(error);return err(error instanceof Error?error:new Error(String(error)))}}function
|
|
3
|
+
`,error);else log.error(error);return err(error instanceof Error?error:new Error(String(error)))}}function identity(file){try{const stat=fs.lstatSync(file,{bigint:true});return{device:stat.dev,inode:stat.ino,directory:stat.isDirectory()}}catch(error){if(error instanceof Error&&"code"in error&&error.code==="ENOENT")return;throw error}}function matches(left,right){return left?.device===right?.device&&left?.inode===right?.inode&&left?.directory===right?.directory}function replaceEntry(source,destination,overwrite){const parent=path.dirname(destination),sourceParent=path.dirname(source);const parentIdentity=identity(parent),sourceParentIdentity=identity(sourceParent),sourceIdentity=identity(source);const lock=path.join(parent,`.stacks-rename-${createHash("sha256").update(destination.normalize("NFC").toLowerCase()).digest("hex")}`);try{fs.mkdirSync(lock,{mode:448})}catch(error){throw new StorageRenameRecoveryError(source,destination,lock,undefined,"lock",false,error)}let lockIdentity;try{const observed=identity(lock);if(!observed?.directory)throw new Error("The acquired storage rename lock changed");lockIdentity=observed}catch(error){throw new StorageRenameRecoveryError(source,destination,lock,undefined,"lock",false,error)}const backup=path.join(lock,"previous"),journal=path.join(lock,"operation.json");let moved=false,installed=false,previous;const unchanged=()=>{if(!matches(parentIdentity,identity(parent))||!matches(sourceParentIdentity,identity(sourceParent))||!matches(lockIdentity,identity(lock)))throw new Error("A storage rename parent or lock changed")};const unlock=()=>{unchanged();if(identity(journal))fs.unlinkSync(journal);fs.rmdirSync(lock)};try{unchanged();if(!sourceIdentity||!matches(sourceIdentity,identity(source)))throw new Error("The source entry changed");previous=identity(destination);const sameEntry=matches(sourceIdentity,previous);if(previous&&!sameEntry&&!overwrite)throw new Error(`File or directory already exists: ${destination}`);fs.writeFileSync(journal,`${JSON.stringify({version:1,source,destination,backup,sourceIdentity,previous},(_,value)=>typeof value==="bigint"?String(value):value)}
|
|
4
|
+
`,{flag:"wx",mode:384});unchanged();if(!matches(previous,identity(destination)))throw new Error("The destination entry changed");try{fs.renameSync(source,destination);installed=true}catch(nativeError){const refusal=nativeError instanceof Error&&"code"in nativeError&&["ENOTEMPTY","EEXIST","EISDIR","ENOTDIR","EPERM"].includes(String(nativeError.code));if(!refusal||!previous||sameEntry||!previous.directory&&!sourceIdentity.directory)throw nativeError;unchanged();if(!matches(previous,identity(destination))||!matches(sourceIdentity,identity(source)))throw new Error("A storage rename entry changed before replacement",{cause:nativeError});fs.renameSync(destination,backup);moved=true;unchanged();if(!matches(previous,identity(backup))||identity(destination)||!matches(sourceIdentity,identity(source)))throw new Error("A storage rename entry changed before installation");fs.renameSync(source,destination);installed=true}}catch(error){if(moved){try{unchanged();if(identity(destination)||!matches(previous,identity(backup)))throw new Error("Cannot restore over changed replacement entries");fs.renameSync(backup,destination)}catch(recoveryError){throw new StorageRenameRecoveryError(source,destination,lock,backup,"rollback",false,error,recoveryError)}}try{unlock()}catch(recoveryError){throw new StorageRenameRecoveryError(source,destination,lock,undefined,"cleanup",false,error,recoveryError)}throw error}try{unchanged();if(!matches(sourceIdentity,identity(destination)))throw new Error("The installed destination entry changed");if(moved){if(!matches(previous,identity(backup)))throw new Error("The previous destination entry changed");fs.rmSync(backup,{recursive:true})}unlock()}catch(error){throw new StorageRenameRecoveryError(source,destination,lock,moved?backup:undefined,"cleanup",installed,error)}}function canonicalEntry(file){const absolute=path.resolve(file);let parent=path.dirname(absolute);const pending=[];while(!fs.existsSync(parent)){pending.unshift(path.basename(parent));const next=path.dirname(parent);if(next===parent)throw new Error(`Cannot resolve the parent of ${file}`);parent=next}return path.join(fs.realpathSync(parent),...pending,path.basename(absolute))}function beneath(child,parent){const route=relative(parent,child);return route!==""&&route!==".."&&!route.startsWith(`..${sep}`)&&!isAbsolute(route)}function directoryContainsEntry(directory,entry){if(!directory?.directory)return false;let parent=path.dirname(entry);for(;;){if(matches(directory,identity(parent)))return true;const next=path.dirname(parent);if(next===parent)return false;parent=next}}
|
package/package.json
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"name": "@stacksjs/storage",
|
|
3
3
|
"type": "module",
|
|
4
4
|
"sideEffects": false,
|
|
5
|
-
"version": "0.75.
|
|
5
|
+
"version": "0.75.552",
|
|
6
6
|
"description": "The Stacks file system.",
|
|
7
7
|
"author": "Chris Breuer",
|
|
8
8
|
"contributors": [
|
|
@@ -61,20 +61,20 @@
|
|
|
61
61
|
"prepublishOnly": "bun run build"
|
|
62
62
|
},
|
|
63
63
|
"dependencies": {
|
|
64
|
-
"@stacksjs/arrays": "0.75.
|
|
65
|
-
"@stacksjs/cli": "0.75.
|
|
66
|
-
"@stacksjs/config": "0.75.
|
|
67
|
-
"@stacksjs/env": "0.75.
|
|
68
|
-
"@stacksjs/error-handling": "0.75.
|
|
69
|
-
"@stacksjs/logging": "0.75.
|
|
70
|
-
"@stacksjs/path": "0.75.
|
|
71
|
-
"@stacksjs/strings": "0.75.
|
|
72
|
-
"@stacksjs/ts-cloud": "^0.16.
|
|
64
|
+
"@stacksjs/arrays": "0.75.552",
|
|
65
|
+
"@stacksjs/cli": "0.75.552",
|
|
66
|
+
"@stacksjs/config": "0.75.552",
|
|
67
|
+
"@stacksjs/env": "0.75.552",
|
|
68
|
+
"@stacksjs/error-handling": "0.75.552",
|
|
69
|
+
"@stacksjs/logging": "0.75.552",
|
|
70
|
+
"@stacksjs/path": "0.75.552",
|
|
71
|
+
"@stacksjs/strings": "0.75.552",
|
|
72
|
+
"@stacksjs/ts-cloud": "^0.16.125",
|
|
73
73
|
"@stacksjs/ts-xml": "^0.1.0",
|
|
74
74
|
"ts-images": "https://registry.pantry.dev/ts-images@22073a9"
|
|
75
75
|
},
|
|
76
76
|
"devDependencies": {
|
|
77
|
-
"@stacksjs/types": "0.75.
|
|
77
|
+
"@stacksjs/types": "0.75.552",
|
|
78
78
|
"better-dx": "^0.2.24"
|
|
79
79
|
}
|
|
80
80
|
}
|