🧱 ファイルストレージブロック
ファイルストレージブロックは、@nodeblocks/backend-sdk の blocks からエクスポートされる再利用可能な署名付きURLとファイル正規化操作です。FileStorageDriver に委譲し、neverthrow 結果を返し、MIMEタイプやサイズ自体の検証やHTTPルートの作成は行いません。
インベントリ
| エクスポート | 種別 | 入力 | 結果 / 動作 / エラー |
|---|---|---|---|
FileStorageServiceError | エラークラス | メッセージ、オプションのデータ | Expected なストレージ操作の失敗。 |
generateSignedUploadUrl | 非同期ブロック | ドライバー、コンテンツタイプ、バイト長さ、オブジェクト名 | ドライバーのアップロードURLを Result で返す; ドライバーの失敗は FileStorageServiceError となる。 |
generateSignedDownloadUrl | 非同期ブロック | ドライバー、オブジェクト名 | ドライバーのダウンロードURLを Result で返す; ドライバーの失敗は FileStorageServiceError となる。 |
generateSignedDeleteUrl | 非同期ブロック | ドライバー、オブジェクト名 | ドライバーの削除URLを Result で返す; 宣言されたエラー型は Error。 |
generateSignedAvatarUploadUrl | 非同期ブロック | ドライバー、コンテンツタイプ、バイト長さ | UUIDオブジェクトIDと署名付きアップロードURL; 宣言されたエラー型は Error。 |
deleteFile | 非同期ブロック | ドライバー、オブジェクト名 | ドライバーの削除結果を Result で返す; 宣言されたエラー型は推論される。 |
generateFileUploadUrl | 非同期ブロック | ドライバー、コンテンツタイプ、バイト長さ | UUIDオブジェクトIDと署名付きアップロードURLを Result で返す。 |
normalizeFile | 非同期ブロック | ドライバー、objectId と type を持つファイル | ファイルフィールドを保持しつつ objectId を除き、signedな url を追加。 |
詳細
FileStorageServiceError
実装
BlockError を継承するが、固有のHTTPステータスを持たない。これを使用するルートは独自のマッピングを選択します。例えばOrganizationアップロードルートはこれを 500 にマッピングする。
generateSignedUploadUrl
実装
シグネチャ: generateSignedUploadUrl(fileStorageDriver: FileStorageDriver, contentType: string, contentLength: number, objectName: string)。Promise<Result<string, FileStorageServiceError>> を返し、未変更の引数を driver.generateSignedUploadUrl に委譲し、ok(url) を返す。拒否されたドライバー呼び出しは err(FileStorageServiceError('Failed to generate signed upload URL.', 'generateSignedUploadUrl')) を返す。
generateSignedAvatarUploadUrl、generateFileUploadUrl、カスタムChat/Productブロック構成によって使用される。
generateSignedDownloadUrl
実装
シグネチャ: generateSignedDownloadUrl(fileStorageDriver: FileStorageDriver, objectName: string)。Promise<Result<string, FileStorageServiceError>> を返す; ドライバーの拒否は FileStorageServiceError('Failed to generate signed download URL.', 'generateSignedDownloadUrl') となる。
normalizeFile およびカスタムAvatar、Organization、Product、Chatブロック構成によって使用される。
generateSignedDeleteUrl
実装
シグネチャ: generateSignedDeleteUrl(fileStorageDriver: FileStorageDriver, objectName: string): Promise<Result<Awaited<ReturnType<FileStorageDriver['generateSignedDeleteUrl']>>, Error>>。ドライバーの署名付き削除URLを返す; 失敗は FileStorageServiceError でラップされるが、パブリックな戻りシグネチャではエラー型として Error が宣言される。カスタム構成のみ; SDKエクスポートルートがこのブロックを直接呼び出すことはない。
generateSignedAvatarUploadUrl
実装
シグネチャ: generateSignedAvatarUploadUrl(fileStorageDriver: FileStorageDriver, contentType: string, contentLength: number): Promise<Result<{objectId: string; url: string}, Error>>。UUID objectId を生成し、contentType から解決された拡張子を付加し、generateSignedUploadUrl に委譲する。成功時は {objectId, url} を返す; 委譲されたブロックからのエラーは未変更で返される。
ソースの getAvatarUploadUrlRoute によって使用される; Profileルート を参照。
deleteFile
実装
シグネチャ: deleteFile(fileStorageDriver: FileStorageDriver, objectName: string): Promise<Result<void, FileStorageServiceError>> (バンドルされたドライバー付き)。objectName を driver.deleteFile に委譲し、解決された値を ok で返す。拒否されたドライバー呼び出しは FileStorageServiceError('Failed to delete file.') を返す。
カスタムAvatar、Profile、Organization、Product、Chatブロック/ハンドラー構成によって使用される; SDKエクスポートルートがこれを直接呼び出すことはない。
generateFileUploadUrl
実装
シグネチャ: generateFileUploadUrl(fileStorageDriver: FileStorageDriver, contentType: string, contentLength: number): Promise<Result<{objectId: string; url: string}, FileStorageServiceError>>。UUID objectId を生成し、contentType から拡張子を導出し、generateSignedUploadUrl を呼び出す。{objectId, url} または委譲されたエラーを返す; 予期せぬthrowされた失敗は FileStorageServiceError('Failed to generate file upload url.') となる。
ソースの getLogoUploadUrlRoute および getCertificateUploadUrlRoute によって使用される; Organizationルート を参照。
normalizeFile
実装
シグネチャ: normalizeFile(fileStorageDriver: FileStorageDriver, fileData: {objectId: string; type: string} & Record<string, unknown>): Promise<Result<{type: string; url: string}, FileStorageServiceError>>。objectId + '.' + extension(file.type) の署名付きダウンロードURLをリクエストし、objectId を削除し、残りのランタイムフィールドを保持し、url を追加する。宣言された成功型は type と url のみを含むが、ランタイムオブジェクトは他の入力フィールドも保持する。任意の失敗は FileStorageServiceError('Failed to normalize file.') となる。
カスタムProfile、Product、Chatブロック構成によって使用される; SDKエクスポートルートがこれを直接呼び出すことはない。