@unikvs/etcd

etcd にバイト列を保存する @unikvs/etcd の使い方を説明します。

概要

@unikvs/etcd は etcd にバイト列を保存するストレージプラグインです。設定の共有やサービスディスカバリーなど、分散協調が必要な場合に使います。

• name は "Etcd" で、isOpen で開閉状態を確認します。
• open() で接続し、使い終わったら close() で解放します。
• このストレージは、キーに名前空間と接頭辞（既定では "unikvs:"）を付与し、clear() の削除範囲を限定します。
• 接続先を省略した場合は、ETCD_ENDPOINTS 環境変数（カンマ区切り）を使い、未設定のときは "http://127.0.0.1:2379" に接続します。
• leaseTtlSeconds を指定すると、書き込んだキーにリースの有効期限（秒）を付与します。

インストールは次のコマンドで行います。

npm install @unikvs/etcd

pnpm add @unikvs/etcd

yarn add @unikvs/etcd

bun add @unikvs/etcd

nub add @unikvs/etcd

aube add @unikvs/etcd

別途 etcd クラスターが必要です。

使い方

Etcd は IStorage を実装しています。UniKvs には persist() で渡します。

import { Etcd } from "@unikvs/etcd";

Etcd

etcd に保存するストレージです。利用者は open() で開き、使い終わったら close() で閉じます。

コンストラクターの引数は次のとおりです。

EtcdStorageOptions

etcd ストレージのオプションです。

EtcdPutOptions

put に渡せる etcd 固有のオプションです。

EtcdGetAllResult

getAll が返すキーと値の組の形式です。レコード、マップ、エントリー反復可能オブジェクトのいずれかです。

EtcdClientLike

etcd クライアントの最小インターフェースです。テストではこのインターフェースを満たすフェイクを注入し、実環境では endpoints から組み立てた etcd3 クライアントを使います。

NativeEtcdClientLike

etcd3 パッケージのクライアントのうち、本パッケージが使う最小部分です。

wrapNativeEtcdClient

etcd3 のネイティブクライアントを EtcdClientLike に適合させます。leaseTtlSeconds 指定時はリース付きで書き込みます。

以下は、値を保存して読み戻す例です。

import { Etcd } from "@unikvs/etcd";
import * as unikvs from "unikvs";

const kvs = new unikvs.Builder<{ file: unikvs.Value<Uint8Array> }>()
  .persist(new Etcd({ endpoints: "http://127.0.0.1:2379" }))
  .build();

await kvs.open();

await kvs.set("file", new Uint8Array([0, 1, 2]));

const data = await kvs.get("file");
console.log(data); // Uint8Array(3) [0, 1, 2]

await kvs.close();

データ型

• write・read にはバイト列 (Uint8Array<ArrayBuffer>) を使います。
• ストリームの読み書きに対応し、チャンクは Uint8Array<ArrayBuffer> です。
• 書き込みストリームはチャンクを蓄積し、完了時に単発の書き込みで保存します。
• 読み取りストリームは取得したバイト列を単一のチャンクとして送出します。

エラー

このパッケージが投げるエラーは次のとおりです。

InvalidLeaseTtlError

コンストラクターの leaseTtlSeconds が正の整数ではないときに投げます。

意味

leaseTtlSeconds に正の整数 (秒) 以外が指定されました。

対処方法

leaseTtlSeconds に正の整数 (秒) を指定してください。

InvalidEndpointsError

コンストラクターの endpoints が空の文字列や空の配列のときに投げます。

意味

endpoints に空の文字列、空の配列、または空文字を含む配列が指定されました。

対処方法

endpoints に空でない文字列か、空でない文字列だけを含む空でない配列を指定してください。

KeyNotFoundError

@unikvs/core の共通エラーです。存在しないキーを読み取ったときに投げます。

意味

指定したキーが存在しません。@unikvs/core の共通エラーです。

対処方法

exists で確認してから読み出してください。

例

以下は、KeyNotFoundError を捕捉する例です。

import { KeyNotFoundError } from "@unikvs/etcd";

try {
  const data = await kvs.get("missing");
} catch (ex) {
  if (ex instanceof KeyNotFoundError) {
    console.log("キーが見つかりません");
  } else {
    throw ex;
  }
}