リポジトリでのConnectorの作成

ActQLのリポジトリにConnectorを追加する方法です。コードをどこに置くか、何を宣言するか、共通のHostが代わりに何を担うか、テストで何を示す必要があるかを説明します。コントリビューター向けのページです。v0.1の間、リポジトリへのConnectorの変更はメンテナーだけが行います（開発を参照）。Connectorとは何で、どう設計するかはConnectorを作るにあります。このページは、リポジトリの中での仕組みです。

共通の意味は、MoonBitのCoreと共通のHostの担当部分に置かれたままです。Connectorが提供するのは、検査済みのインストールマニフェストと物理的なドライバーです。処理が完了したかどうかを決めるのはCoreです。

配置Copy Anchor Link

Connectorは、計画、実行、トランスポートのつなぎ、外部インターフェースを、自分のルートの下に持ちます。共通のスケジューリング、組み立て、Connectorをまたぐ検証は、どのConnectorのツリーの外にもあります。

src/connectors/<name>/
  acquisition/        source acquisition
  adapter/            query and physical-value compilation
  compute/            fixed-input compute support (when the system can compute)
  driver/             common Host lifecycle integration
  host/               acquisition Host bridge
  host_native/        native Host bridge
  host_node/          Node Host bridge
  adapters/native/    Connector-specific native FFI (when needed)
  conformance/        test-only real-engine fixtures
  host-bundle.json    installation manifest (sources, Effects, exports)
  compute-bundle.json compute contribution manifest (when applicable)

adapters/connectors/<name>/node/
  Node I/O: HTTP, SDK sessions, native integration

次の3つの制約がリポジトリのゲートで強制されます。

1. 共通の実行パッケージは、src/connectors/ 配下のパッケージに直接も推移的にも依存しない。
2. 製品パッケージは適合性パッケージをインポートしない。
3. ローカル専用のバンドルには、DuckDBパッケージ、Nodeアダプター、ネイティブFFI、リンクされたライブラリのマーカーが含まれない。

新しいConnectorは、これらのConnectorが持つルートを広げるものであって、製品固有のトップレベルのプラットフォームパッケージを足すものではありません。src/platform_native/ は、ファイルシステム、HTTP、SQLiteのような、製品に依存しないOSの機能のために予約されています。

宣言Copy Anchor Link

1. src/connectors/<name>/host-bundle.json に、SourceとEffectのロールを宣言する。プロファイルのバージョン、登録とリビジョン、アダプターのモジュール、そして check、identity、publish、load の正確なエクスポート。読み取り専用のConnectorはEffectを宣言しない。

2. 必要な場合にだけ、純粋なコーデックのパッケージを providerBundle として宣言し、自分が持つ静的ファイルを assets として宣言する。暗黙のパッケージ解決、外部のエイリアス、宣言されていないファイルシステムへの依存は使わない。

3. そのシステムが計算できる（絞り込み、集計など）なら、compute-bundle.json に計算の貢献を宣言する。設定の型、純粋な構築関数、登録のアクセサー、貢献のファクトリー、診断用のエラー型。

4. アセンブリを再生成して検査する。

   Copy Text

   node scripts/connector-node-bundles.mjs --write
   node scripts/connector-compute-bundles.mjs --write
   moon check --target all --deny-warn

   インストールの一覧と標準パッケージの目録は、マニフェストから生成される。src/connectors_builtin は生成物なので、手で編集しない。

5. 共通の行ソースHost（client_row_source_host）を通して、型付きのCatalogとSourceViewを復元する。そのMappingのファクトリーと、検査環境の権限チェックを使う。ドライバーが証拠を自分で組み立てたり、Connectorが宣言していない操作を受け付けたりすることはない。

レコードを指定できるMappingは、必須で非nullableのスカラーの識別子を持ちます。コレクションだけのMappingは、主たる識別子を持たず、型付きのコレクションの識別子を持ち、create だけを許します。対応していない操作は、登録と検査の段階で拒否され、物理的な送信まで持ち込まれることはありません。

共通の担当部分がすること、ドライバーが提供することCopy Anchor Link

読み取り：createInstalledRowSource が、検査済みの取得、ページの課金、取り込み、入力の束縛、ソースの証拠を担います。ドライバーは physicalTarget と有限の readPages を提供し、渡されたページごとの認可とスコープ付きの認証情報を使います。ドライバーは2つ目の台帳を持たず、自分で成功を発行しません。射影の前にバイト列を観測し、APIのエラーを空の入力や NULL に置き換えることはありません。

書き込み：createInstalledRowEffect が、検査済みのプレビュー、Setの承認、永続的なクレーム、保存した応答、受領記録、公開、復旧を担います。書き込みの種類ごとに、ドライバーは純粋な prepareRequest と requestFacts、writeOperation、ちょうど1つの物理的な send、応答の project、有界の footprint を提供します。共通の担当部分は、送信の前に、正確な値とセレクターをプログラムおよびプレビューと比較します。

対象を指定する書き込みは、対象の観測とバージョンのフックも提供します。独自の復旧は、recoveryEntry、recoverRequests、requestCid をそろえて提供します。不完全な組は登録で拒否されます。復旧は、承認された正確なリクエストを再構築して比較しなければなりません。保持されたデータは認可ではありません。create だけのドライバーは、既定の再構築を使えます。

拒否の分類は、送信の前に観測した意味上の事実からだけ行います。拒否のマーカーは、例外、レート制限、応答の欠落、物理的な停止をまとめて受ける器ではありません。権威あるルックアップも冪等性もないシステムでは、送られた可能性のある書き込みを unknown のままにしなければなりません。同じ値を読み返せたからといって、成功をでっち上げてはいけません。

クローズとクリーンアップの失敗は、同じ再試行のハンドルに残ります。完了と印を付けるのは、クローズが成功したあとだけです。再試行はリソースを解放するもので、読み取り、計算、プレビュー、承認、送信を繰り返すことは決してありません。

Connectorが通さなければならないテストCopy Anchor Link

adapters/host-node/ 配下のインストール済みEffectのテストスイートにある、共通の登録、値の比較、準備段階での拒否、応答の復旧、クリーンアップのフィクスチャを、自分のシステム用の独立したデータで再利用し、システム固有の境界のケースだけを足します。

• 対応している登録と準備。宣言されていない操作と、不完全なフックの組の拒否
• Unicodeを含む、正確な型付きの値、セレクター、対象、リクエストの識別子
• 承認前の送信は0回、許可されたクレームごとに送信は1回
• 保存した成功と、不明な結果の、再送なしでの再構築
• 送信前に権限や対象が変わったときの拒否
• クリーンアップに失敗しても試行の記録を保つこと、再試行で再計算しないこと
• 有限のコーデックとトランスポートの上限。ちょうどの場合と1つ足りない場合
• 公開パッケージのエクスポートだけを使った外部からのインストール

ローカルの応答者は、テストの中で実際のサービスの代わりをするものです。実際のサービスに対するテストは別に行い、フィクスチャの結果で代用はできません。Connectorが実際に対応するクエリと書き込みのプロファイルを宣言してください。言語のあらゆる形ではありません。