エンティティストレージ
IOmnioEntity、IOmnioEntityBuilder、unikvs の接続方法のリファレンスです。
役割
エンティティストレージは、オブジェクトのバイト列を entityId ごとに保存します。Omnio はキーと entityId の対応をインデックスに保存し、バイト列はエンティティストレージから読み出します。
IOmnioEntity
interface IOmnioEntity {
open(options?: { signal?: AbortSignal }): Promise<void>;
close(options?: { signal?: AbortSignal }): Promise<void>;
has(key: string, options?: { signal?: AbortSignal }): Promise<boolean>;
get(key: string, options?: IOmnioEntityReadOptions): Promise<Uint8Array>;
set(
key: string,
value: Uint8Array | ReadableStream<Uint8Array>,
options?: { vars?: IOmnioEntityVariables; signal?: AbortSignal },
): Promise<void>;
copy(key: string, destinationKey: string, options?: { signal?: AbortSignal }): Promise<void>;
delete(key: string, options?: { signal?: AbortSignal }): Promise<void>;
stream(key: string, options?: IOmnioEntityReadOptions): Promise<IValueStream<Uint8Array>>;
}
| メソッド | 説明 |
|---|---|
open |
ストレージを開きます。 |
close |
ストレージを閉じます。 |
has |
キーが存在するか返します。 |
get |
バイト列を取得します。存在しなければエラーです。 |
set |
バイト列またはストリームを保存します。 |
copy |
バイト列を別のキーへ複製します。 |
delete |
バイト列を削除します。存在しない場合は何もしません。 |
stream |
バイト列のストリームを返します。 |
get と stream は vars を受け取ります。Omnio はここに SHA-256 の期待値を渡し、ストレージのミドルウェアが読み取り時に検証します。
IOmnioEntityBuilder
interface IOmnioEntityBuilder {
build(options?: UniKvsBuildOptions): IOmnioEntity;
}
Omnio はコンストラクターで build() を実行し、チェックサム用のミドルウェアを beforeAll に指定します。実装では、受け取ったオプションを unikvs の build() に渡してください。
type EntityMapping = Record<string, unikvs.Value<Uint8Array>>;
const entity = new unikvs.Builder<EntityMapping>().persist(new NodeFs("./data/entities"));
unikvs のストレージ
| パッケージ | 保存先 | 用途 |
|---|---|---|
@unikvs/memory |
メモリー | テスト、試作 |
@unikvs/fs.node |
Node.js のファイルシステム | Node.js の永続化 |
@unikvs/opfs |
Origin Private File System | ブラウザーの永続化 |
NodeFs にはルートディレクトリーを、Opfs には OPFS 内のルート名を渡します。
import { NodeFs } from "@unikvs/fs.node";
const entity = new unikvs.Builder<EntityMapping>().persist(new NodeFs("./data/entities"));
import { Opfs } from "@unikvs/opfs";
const entity = new unikvs.Builder<EntityMapping>().persist(new Opfs("omnio-entities"));
エンティティの不変性
Omnio は一度保存した entityId のバイト列を変更しません。
putObjectとcopyObjectは新しいentityIdを割り当てます。renameObjectは同じentityIdを維持します。- 上書き時も新しい
entityIdを割り当てます。
同じ entityId のバイト列を外部から書き換えると、チェックサム検証に失敗したり、読み取り中のストリームが壊れたりします。
チェックサム
Omnio は SHA-256 を計算するミドルウェアをエンティティストレージのビルダーに注入します。保存時にハッシュを取得し、インデックスに hash と hashAlgorithm: "sha256" を記録します。
読み取り時は次のように動きます。
getObject: 返す前にチェックサムを検証します。一致しなければChecksumMismatchErrorが投げられます。streamObject: ストリームの終端で検証します。途中でキャンセルすると検証されません。
エンティティストレージのビルダーに別の ChecksumSha256 が含まれていても、Omnio が注入したインスタンスの結果だけを使います。
ストリーム
IOmnioEntity.stream は IValueStream<Uint8Array> を返します。streamObject で取得したストリームは、呼び出し側で使い切るか破棄してください。
const stream = await omnio.streamObject("large/file.bin");
if (stream !== null) {
for await (const chunk of stream) {
// chunk を処理します。
}
}