v0.21

ストレージ

はじめに

dframeworkはStorageファサードを通じてファイルシステム抽象化を提供します。設定された複数のディスクにわたってファイルを簡単に読み書きおよび管理できます。ストレージサービスはパストラバーサルの防止や公開アセットのシンボリックリンク作成、並行操作キューイング、ディスク容量の検証を自動的に管理します。

設定

ストレージ設定はconfig/storage.jsのstorage.disks設定名前空間内で定義します。一般的な設定にはプライベートファイル用のlocalディスク、公開アセット用のpublicディスク、暗号化ファイル用のsecureディスクが含まれます。

1import { Env } from 'dframework';
2
3export default {
4 disks: {
5 local: {
6 root: './storage/local',
7 },
8 public: {
9 root: './storage/public',
10 },
11 secure: {
12 root: './storage/secure',
13 encryptionKey: Env.value('APP_KEY'),
14 },
15 },
16};

dframeworkは起動時にpublic/storageからstorage/publicへのシンボリックリンクを自動作成するためpublicディスクに保存されたファイルはブラウザへ直接配信できます。

ディスクインスタンスの取得

ディスクインスタンスを取得する標準的な記述はStorage.disk(name)の呼び出しです。ディスク名を省略するとconfig/storage.jsで設定されたデフォルトディスク(未設定時はpublic)に解決されます。

利便性のためにStorageファサードはデフォルトディスクへの直接プロキシ操作(Storage.put()、Storage.get()、Storage.delete()など)も提供します。

1import { Storage } from 'dframework';
2
3await Storage.disk().put('notes.txt', 'hello');
4
5await Storage.put('notes.txt', 'hello');
6
7const disk = Storage.disk('local');

ファイルの保存

ディスクにファイルを書き込むにはputメソッドを使用します。第1引数に相対ファイルパス、第2引数にファイル内容(文字列またはバッファ)を渡します。必要なディレクトリは自動作成されます。

1await Storage.disk().put('avatars/1.jpg', imageBuffer);
2await Storage.disk('local').put('exports/report.csv', 'id,name\n1,tarou');

ファイルアップロード

putメソッドはhttpアップロード時に生成されるマルチパートファイルオブジェクトに対応しています。アップロードされたファイルオブジェクトを直接putに渡すことで手動でのバッファ展開なしにストリーミング書き込みが実行されます。

1const path = await Storage.disk().put('avatars/user.jpg', req.file('avatar'));

ファイルの取得

ファイル内容を読み取るにはgetメソッドを使用します。デフォルトでは生のBufferを返します。文字列として取得したい場合は第2引数にutf8などの文字エンコーディングを指定します。

1const raw = await Storage.disk('local').get('documents/contract.pdf');
2const text = await Storage.disk('local').get('reports/summary.txt', 'utf8');

ファイルが存在するかどうかはexistsメソッドで確認できます。

1if (await Storage.disk().exists('avatars/1.jpg')) {
2}

ディスク上の絶対パスが必要な場合はpathメソッドを使用します。

1const absolutePath = Storage.disk('local').path('exports/report.csv');

ファイルの削除

ファイルを削除するにはパスをdeleteメソッドに渡します。ファイルが削除された場合はtrue、存在しなかった場合はfalseを返します。

1await Storage.disk().delete('avatars/1.jpg');

ファイル管理

同一ディスク内でのファイル移動や複製を行うメソッドも用意されています。

1await Storage.disk().move('temp/draft.txt', 'published/final.txt');
2
3await Storage.disk().copy('templates/invoice.pdf', 'invoices/123.pdf');

暗号化

encryptionKeyが設定されたディスクは書き込み時に自動暗号化され読み取り時に自動復号されます。アルゴリズムはaes-256-gcmです。鍵は提供された文字列からsha256経由で導出されます。暗号化キーはファイル内には保存されず環境設定(APP_KEY)内でのみ保持されます。apiは非暗号化ディスクと同一です。

ディスク上のフォーマットは12バイトivと16バイト認証タグと暗号文で構成されます。認証タグにより改ざん検知が行われファイルが変更されていた場合は読み取りが失敗します。

1await Storage.disk('secure').put('keys/api-key.txt', 'my-secret-value');
2
3const value = await Storage.disk('secure').get('keys/api-key.txt', 'utf8');

ディスク容量の保護

ディスク容量枯渇によるアプリケーション停止を防ぐためストレージサービスは書き込み前に容量の健全性チェックを実行します。

NOTE

`put()`による書き込み前にストレージサービスは対象ディスクにデータサイズに加えて100メガバイトの安全マージンがあるかを検証します。容量が不足している場合書き込み処理は安全に中断されます。