💾 ファイルストレージドライバー

ファイルストレージドライバーは、NodeBlocks アプリケーションで安全なファイル操作を行うための一貫したインターフェースを提供します。クラウドストレージの設定と署名付き URL の生成を抽象化し、SDK のサービスおよびブロックから利用できます。

---

🎯 概要

NodeBlocks のファイルストレージドライバーは、署名付き URL の機能を備えた設定済みの Google Cloud Storage インスタンスを作成するファクトリー関数です。現在、SDK には GCS ドライバーが 1 つ含まれています。

import { drivers } from '@nodeblocks/backend-sdk';

const { createFileStorageDriver } = drivers;

---

📋 利用可能なファイルストレージドライバー

Google Cloud Storage ドライバー

Google Cloud Storage ドライバーは、署名付き URL を生成できる設定済みのファイルストレージインスタンスを作成します。

前提条件

このドライバーを使用するには、Application Default Credentials で Google Cloud SDK クライアントを認証します。ローカル開発では、次の手順を利用できます。

• バケットへのアクセス権を持つ Google Cloud サービスアカウントを作成する
• サービスアカウントの JSON キーファイルをダウンロードする
• GOOGLE_APPLICATION_CREDENTIALS 環境変数に JSON キーファイルの絶対パスを設定する

このドライバーは Application Default Credentials に依存するため、認証情報を createFileStorageDriver に直接渡すことはありません。上記の環境変数の設定は、ADC を提供する方法の 1 つです。

createFileStorageDriver

署名付き URL の機能を備えた Google Cloud Storage ファイルストレージドライバーを作成します。これは同期ファクトリーのため、await は不要です。

パラメーター:

パラメーター	型	説明
projectId	string	Google Cloud プロジェクト ID
bucketName	string	ファイル操作に使用するストレージバケット名
options?	{ signedUrlExpiresInSeconds: number }	任意の設定（既定の有効期限: 900 秒）

戻り値: FileStorageDriver — 署名付き URL を生成するメソッドを持つファイルストレージドライバー

使用例:

import { drivers } from '@nodeblocks/backend-sdk';

const { createFileStorageDriver } = drivers;

const fileStorage = createFileStorageDriver(
  process.env.GCP_PROJECT_ID!,
  process.env.GCP_BUCKET_NAME!
);

有効期限をカスタマイズする例:

import { drivers } from '@nodeblocks/backend-sdk';

const { createFileStorageDriver } = drivers;

const fileStorage = createFileStorageDriver(
  'my-project-id',
  'my-storage-bucket',
  { signedUrlExpiresInSeconds: 1800 } // 30 分
);

FileStorageDriver

drivers 名前空間からエクスポートされる型エイリアスです（src/drivers/file-storage.ts では Awaited<ReturnType<typeof createFileStorageDriver>>）。deleteFile、generateSignedDeleteUrl、generateSignedDownloadUrl、generateSignedUploadUrl を公開します。パラメーターと動作は、以下の「ファイルストレージドライバーのメソッド」を参照してください。

この型は SDK プリミティブにおけるサービス注入用の型として使用されます。

署名付き URL の実装

すべての署名付き URL メソッドでは、GCS の v4 署名（version: 'v4'）を使用します。有効期限は次のように計算されます。

Date.now() + signedUrlExpiresInSeconds * 1000

メソッド	GCS action	備考
generateSignedUploadUrl	'write'	contentType と extensionHeaders: { 'Content-Length': contentLength } を含みます
generateSignedDownloadUrl	'read'	—
generateSignedDeleteUrl	'delete'	—

---

🔧 ファイルストレージドライバーのメソッド

deleteFile

Google Cloud Storage バケットからファイルを削除します。

パラメーター	型	説明
objectName	string	バケットから削除するストレージオブジェクト名／パス

戻り値: Promise<void>

await fileStorage.deleteFile('uploads/temp-file.jpg');

generateSignedDeleteUrl

ファイル削除操作用の署名付き URL を生成します。

パラメーター	型	説明
objectName	string	削除するストレージオブジェクト名／パス

戻り値: Promise<string>

const deleteUrl = await fileStorage.generateSignedDeleteUrl('uploads/temp-file.jpg');

generateSignedDownloadUrl

ファイルダウンロード操作用の署名付き URL を生成します。

パラメーター	型	説明
objectName	string	ダウンロードするストレージオブジェクト名／パス

戻り値: Promise<string>

const downloadUrl = await fileStorage.generateSignedDownloadUrl('uploads/document.pdf');

generateSignedUploadUrl

ファイルアップロード操作用の署名付き URL を生成します。

パラメーター	型	説明
contentType	string	アップロードするファイルの MIME タイプ
contentLength	number	リクエスト本文の正確なサイズ（バイト）。Content-Length ヘッダーとして署名されます
objectName	string	アップロード先のストレージオブジェクト名／パス

戻り値: Promise<string>

const uploadUrl = await fileStorage.generateSignedUploadUrl(
  'image/jpeg',
  5 * 1024 * 1024, // リクエスト本文の正確なサイズ
  'uploads/profile-avatar.jpg'
);

アップロードクライアントの要件:

要件	詳細
HTTP メソッド	PUT
Content-Type ヘッダー	generateSignedUploadUrl に渡した contentType と一致している必要があります。不一致の場合は 403 が返されます
本文サイズ	指定した contentLength と同じである必要があります。異なるサイズの場合は 403 が返されます

エラー時の動作:

結果	動作
ADC が無効、またはバケットアクセスに失敗	すべてのメソッドがエラーをスローします
存在しないオブジェクトに対する deleteFile	エラーをスローします（オブジェクトが存在しません）
Content-Type が不正、または本文サイズが異なるアップロード	署名付き URL リクエストに対して GCS が 403 を返します

---

🔧 ファイルストレージドライバーの使用

サービスでの使用

fileStorageDriver を受け取るサービスの第 3 引数のオプションを通じてドライバーを注入します。

import { services, drivers } from '@nodeblocks/backend-sdk';

const { organizationService } = services;
const { createFileStorageDriver } = drivers;

const fileStorageDriver = createFileStorageDriver(
  process.env.GCP_PROJECT_ID!,
  process.env.GCP_BUCKET_NAME!
);

organizationService(
  dataStores, // 組織サービスには identities、organizations、profiles が必要
  {
    authSecrets: {
      authEncSecret: process.env.AUTH_ENC_SECRET!,
      authSignSecret: process.env.AUTH_SIGN_SECRET!,
    },
  },
  { fileStorageDriver }
);

Express の完全な配線と必要なデータストア（identities、organizations、profiles）については、組織サービス を参照してください。同じ fileStorageDriver の注入パターンは、プロフィールサービス、商品サービス、チャットサービス にも適用されます。

---

🔗 関連ドキュメント

• ドライバー概要 — ドライバーエクスポートの完全な一覧
• ファイルストレージブロック — ドライバーを使用するファイルストレージ操作
• ファイルストレージスキーマ — ファイルストレージの検証スキーマ