サイドカー

実行時の責任

サイドカーは、デスクトップとローカル開発統合によって共有される Bun バックエンドです。 SQLite を開き、リポジトリとドメイン サービスを提供し、スキーマ定義の HTTP API を提供し、アシスタントとワークフローの統合をホストします。 Tauri シェルはパッケージ化されたバイナリを起動し、マシン可読な起動イベントから割り当てられたポートを検出します。

apps/sidecar/src/layers.ts 提供される API、ハンドラー、認可、リポジトリ、およびサービスを構成します。有料チェックアウトや AI モデルなどのオプションのプロバイダーは、サービスを通じて構成されます。これらが存在しないからといって、データベース レコードが機能する外部統合に変わるわけではありません。

プロセスとシャットダウンのプロトコル

メインの HTTP サーバーはバインドのみを行います 127.0.0.1、ポート付き 0 したがって、オペレーティング システムは利用可能なポートを選択します。 HTTP アイドル タイムアウトは無効になっており、ストリーミング イベント間で長時間のアシスタント コールがサイレントのままであることが可能です。正常な HTTP シャットダウンは、スコープの終了処理が続行されるまでの 500 ミリ秒間設定されています。

API の公衆衛生プローブが成功すると、プロセスは標準出力に Ready イベントを出力します。起動に失敗すると、エラー イベントが出力され、失敗した終了コードが設定されます。操作ログは JSON として標準エラー出力に保存されます。 stdout は親プロセス プロトコル用に予約されています。

{"event":"ready","port":53211}
{"event":"error","message":"Startup failure details"}

改行で終了する標準入力メッセージ event: "shutdown"、stdin クロージャ、SIGINT、または SIGTERM はサーバー スコープを解放します。不正な親メッセージは無視され、大きすぎる不完全な行は破棄されます。ファイナライザーは所有されているサービスを停止し、SQLite をチェックポイント/クローズします。割り込みのみの終了は正常な終了として報告されます。

必要な構成

AppConfigService プロセス構成を一度読み取ります apps/sidecar/src/config.ts. CADCAMFUN_TOKEN は必要なアプリケーションベアラートークンであり、 CADCAMFUN_DATA_DIR は、必要なアプリケーション データ ディレクトリです。データベースのパスは <dataDir>/cadcamfun.db. CADCAMFUN_MIGRATIONS_DIR オプションであり、SQL 移行フォルダーを提供します。これがないと、データベース層はアプリケーションの移行を適用しません。

デスクトップは起動構成を提供します。直接開発の場合は、起動シェルでこれらの構成名を指定し、リポジトリ ルートからパッケージの開始スクリプトを実行します。

bun run --filter @cadcamfun/sidecar start

サイドカー パッケージの定義 start そして typecheck スクリプト。パッケージ化されたバイナリ コンパイルは、サイドカー パッケージではなく、リポジトリ リリース スクリプトによって所有されます。 build 指示。

オプションの構成

• CADCAMFUN_APP_URL 認証リンクのベースを設定します。 CADCAMFUN_DEBUG_LINKS デバッグ リセット/マジック リンクを返すことを有効にし、デフォルトは false です。
• CADCAMFUN_AI_HOST は nikcli (デフォルト; チャットは埋め込み会話ホストを通じて実行されます) または direct (AI SDK のみ)。 CADCAMFUN_AI_OFFLINE (ブール値、デフォルトは false) オプションのモデル-カタログ ネットワーク パスを無効にします。 CADCAMFUN_AI_MINIMAX_BASE_URL miniMax のエンドポイントをオーバーライドします。
• STRIPE_SECRET_KEY stripe プロバイダーを有効にします。 STRIPE_PRICE_BASIC, STRIPE_PRICE_PRO、 そして STRIPE_PRICE_ENTERPRISE 有料プランの価格を提供します。 STRIPE_WEBHOOK_SECRET 署名付き Webhook 検証には必須です。
• CRON_SECRET cron ルートのシークレットを提供します。これがなければ、ローカル アプリケーションは追加の cron シークレットなしでそのルートを呼び出すことができます。 ADMIN_EMAIL 従来の管理者の ID チェックです。デフォルトでは、ローカル プロファイルはそれ自体のインストールの管理者になります。
• OTEL_EXPORTER_OTLP_ENDPOINT 設定された OTLP テレメトリのエクスポートを有効にします。エンドポイントがない場合、外部テレメトリのエクスポートはオフになります。

これらの名前はすべて 1 か所で読み上げられます。 AppConfigService;トークンと Stripe 秘密キーは編集された値として保持されるため、ログには表示されません。 AI プロバイダーのキーは、認証情報 API と専用の認証情報ファイルを通じて管理されます。これらは、ベンダー API キー環境設定として読み取られません。 AppConfigService.

HTTPアクセスとAPIディスカバリ

サイドカーが公開します /api/openapi.json サービス対象のコントラクトに対して、保護されたグループでベアラー ミドルウェアを使用します。 2 番目のオプションのセッション ヘッダーでは、代理アカウントを選択します。ローカル プロファイルは次の場所で作成または再利用されます。 local@cadcamfun.local、アカウントのサインインなしでインストールを使用できるようにします。

CORS は認める tauri://localhost、HTTP/HTTPS tauri.localhost、および HTTP localhost または 127.0.0.1 のオリジンとオプションのポート。他のオリジンは、allowed-origin 応答ヘッダーを受け取りません。 CORS はブラウザーのポリシーです。ベアラー ミドルウェアは、引き続き保護されたルートのアクセス制御を行います。

提供されるグループには、設計リソース、製造生成と検証、正確な CAD、ライブラリ、コスト、AI、VCS/ワークフロー、イベント、コンパニオン コントロール、ID、組織、通知、ファイル、プラグイン、請求、分析、待機リスト、MCP、およびローカル状態が含まれます。メソッドとペイロードの詳細については、実行中の OpenAPI ドキュメントを参照してください。

代理アカウントのヘッダーは次のとおりです。 x-session-token。これがない場合、または既存のユーザーのセッション トークンとして検証されないトークンを使用した場合、リクエストはローカル プロファイルとして機能します (src/http/authorization.ts).

ソース組織

main.ts スコープ指定されたサーバーと親プロトコルを起動します。 config.ts 供給構成、 layers.ts 依存関係をワイヤリングし、 startup.ts 準備状況とループバック ポートを共有します。 shutdown.ts 親シャットダウンメッセージを読み取り、 observability.ts オプションのテレメトリを設定します。

http/ 検証されたリクエストをサービスにマッピングします。 repos/ リソースを Drizzle クエリとリソース アクセス ルールにマップします。 services/ リソース間の動作を調整し、 plugins/ ワーカーホストとブラウザーのブートストラップ実装が含まれています。

ハンドラーグループ

ハンドラーは、プロジェクト、図面、コンポーネント、ツールパスとエクストラ、ツールパス ジェネレーター、正確な CAD、材料/ツール/マシン構成とそのストレージ ルート、ライブラリ、コスト、ファイル、組織、通知、ユーザー/認証、請求、分析、待機リスト、MCP、その他のアプリケーション サービス、キーと値の状態、AI、VCS、イベント、コンパニオン管理などのリソースごとにグループ化されています。

entity-io.ts エンティティのインポート/エクスポート ヘルパーを共有します。 authorization.ts アプリケーションおよびスコープ指定されたブリッジの資格情報を適用します。ハンドラーの宣言されたペイロードはすでにスキーマ デコードを通過しています。サービスレベルの検証では、参照、所有権、証拠の一貫性、およびドメインの制約が引き続きチェックされます。

ドメインサービス構成

AI サービスは、描画と CAM アクション、パラメトリック/正確な検査、プロジェクト コンテキスト、メモリ、作業者ジャーナル、およびプラグイン ツールを提供します。 cam-program.ts キャプチャされた製造リクエストを再実行し、保存中にネイティブの証拠を検証します。履歴サービスは、スナップショット、保護されたブランチ ルール、GitHub トランスポート、およびワークフローの実行を適用します。

他のサービスは、ファイル ストレージ、コスト計算、ローカル プロファイルと代理ユーザーの状態、トークンの署名/失効、ブリッジ資格情報、支払い、通知、ライブ イベント、およびコンパニオンのライフサイクルを所有します。エフェクト レイヤーはリソースを所有しているため、シャットダウンすると依存関係の順序でリソースが解放されます。

リポジトリ境界

リポジトリは共有を使用します Database.query 永続性と型指定されたストレージ障害のためのサービス。これらは、保存された JSON をデコードし、リソース固有のアクセスを強制したり、認可ヘルパーを提供したりします。 HTTP ハンドラーは、ドメイン/ストレージの障害を宣言された応答エラーに変換します。ジオメトリ計算はそのまま残ります @cadcamfun/core.

プラグインの統合

一般ワーカーホストは plugins/host.ts。 Production Assistant プラグイン サービスのロードが明示的に有効になっている ai:tool アプリケーションプラグインディレクトリからの拡張子。ブラウザーの ZIP インストーラーとブートストラップ API は、独自のマニフェストとストレージ パスを使用します。見る プラグイン 拡張形式を選択する前、または機能が有線であると想定する前に。

コンパニオンHTTPSゲートウェイ

コンパニオン ゲートウェイは、以前に有効にした設定を再開できる別個のオプトイン HTTPS リスナーです。ネットワーク クライアントの IPv4 をバインドし、生成された証明書が保持されるように提示します。 <dataDir>/companion、スコープ付きの取り消し可能なデバイス トークンを使用します。ペアリングにより証明書のフィンガープリントが提供されるため、モバイル トランスポートがデスクトップを固定できるようになります。

ゲートウェイは明示的なルート許可リストをチェックし、許可されたリクエストをアプリケーション トークンを使用してループバック API に転送します。ペアリングされた電話機がそのアプリケーション トークンを受信することはありません。この許可リストには、認証情報の管理、プラグインのインストール、ファイル管理、および請求は含まれません。デバイスを取り消すか、ゲートウェイを無効にすると、そのネットワーク アクセスが削除されます。

準備と診断

Ready イベントは、サーバー層の構築後にローカル HTTP 正常性プローブが成功したことを意味します。これは、モデル プロバイダーがリクエストを受け入れたこと、チェックアウトが設定されたこと、またはすべてのオプションのネットワーク サービスが到達可能であることを意味するものではありません。これらのサービスは、独自のステータスと結果のエンドポイントを通じて診断します。

起動エラーの場合は、プロトコル メッセージと関連する標準エラー出力イベントを保持し、構成と移行を確認し、データ ディレクトリのアクセス可能性を検査します。起動ベアラー トークンまたはプロバイダーの資格情報の内容を診断出力に貼り付けないでください。

データの所有権

永続データには、SQLite データベースと移行バックアップ、ファイル ストレージ、AI 資格情報/構成状態、認証シークレットと失効レコード、プラグイン アセット、コンパニオン証明書が含まれます。アプリケーション データ ディレクトリ全体をバックアップしたり、インストールを転送したりする場合は、それを保護します。サイドカーは接続の有効期間を所有します。クライアントは SQLite ハンドルもメインベアラー トークンの発行も所有しません。

使い捨てローカルインスタンスを起動する

専用ターミナルのリポジトリ ルートでこれらのコマンドを実行します。ディレクトリは新しく、トークンは印刷せずにローカルで生成され、移行は明示的で、直接/オフライン AI モードでは、この起動チェックのために埋め込み会話ホストをインポートする必要がありません。 openssl このシェルの例では、ランダムな起動トークンを提供します。

export CADCAMFUN_DATA_DIR="$(mktemp -d /tmp/cadcamfun-docs.XXXXXX)"
export CADCAMFUN_TOKEN="$(openssl rand -hex 32)"
export CADCAMFUN_MIGRATIONS_DIR="$PWD/packages/db/drizzle"
export CADCAMFUN_AI_HOST=direct
export CADCAMFUN_AI_OFFLINE=1
bun run --filter @cadcamfun/sidecar start

固定番号を想定するのではなく、ready イベントのポートを読み取ります。サービスの実行中は標準入力を開いたままにしてください。すでに終了した入力ソースからのパイプは、シャットダウンを要求します。 SIGTERM またはシャットダウン プロトコルを使用してデータベースを解放します。使い捨てディレクトリは、終了後も検査のために使用できます。

クライアント シェルですでに利用可能な接続 URL とそのトークンを使用して、パブリックな稼働状態と保護されたアクセスを比較します。

curl --fail-with-body "$CADCAMFUN_URL/api/health"
curl --fail-with-body -H "Authorization: Bearer $CADCAMFUN_TOKEN" "$CADCAMFUN_URL/version"
curl --fail-with-body -H "Authorization: Bearer $CADCAMFUN_TOKEN" "$CADCAMFUN_URL/api/projects"

ソース： apps/sidecar/src/main.ts, config.ts, shutdown.ts、 そして test/process.test.ts.

ログとオプションのテレメトリ

Stderr JSON ログと stdout ready/error イベントには異なるコンシューマがあります。ランチャーは完全な stdout 行を解析し、stderr を個別に転送または保持する必要があります。準備完了後に失敗したリクエストはアプリケーション エラーであり、2 番目の起動イベントではありません。

いつ OTEL_EXPORTER_OTLP_ENDPOINT 設定されており、 ObservabilityLive スパン/ログのバッチ処理と定期的なメトリックのエクスポートを設定します。追加します /v1/traces, /v1/metrics、 そして /v1/logs 末尾のスラッシュを削除した後、提供されたコレクタ ベースに追加します。などのコレクターベースを供給します。 http://collector:4318すでにサフィックスが付いているシグナル URL ではなく、

リソースサービス名は cadcamfun-sidecar そのバージョンはアプリケーション構成から取得されます。標準の OpenTelemetry リソース環境設定は、SDK によって処理されます。ネットワーク エクスポートはオプションですが、コレクタが設定されていない場合でもローカルの標準エラー出力は引き続き使用できます。

ソース： apps/sidecar/src/observability.ts そして main.ts.

失敗した境界を特定する

実際のプロセスのライフサイクル テストでは、EOF、分割シャットダウン JSON 行、および SIGTERM がカバーされ、その後、同じデータ ディレクトリを再起動して、永続化されたプロジェクトを検証します。また、終了後に WAL も検査します。これにより、ソース プロセスのライフサイクル動作が確立されます。パッケージ化されたシェルとマシン固有の配信には、依然として独自の検証が必要です。

ソース： apps/sidecar/test/process.test.ts, src/http/authorization.ts, src/layers.ts、 そして src/services/companion.ts.

起動シーケンスの詳細

1. シェルは、32 文字として 16 進エンコードされた 64 ランダム バイトの起動トークンを生成し、次のコードでサイドカーを開始します。 CADCAMFUN_TOKEN, CADCAMFUN_DATA_DIR、 そして CADCAMFUN_MIGRATIONS_DIR.
2. AppConfigService すべての設定を一度読み取ります。必要な設定が欠落しているため、起動に失敗し、 error イベント。
3. データベース層が開きます <dataDir>/cadcamfun.db、WAL モードと外部キーを有効にし、移行ディレクトリから移行を適用します。
4. レイヤーは、データベース、リポジトリ、サービス、HTTP ハンドラーの順に構成されます。すべてのリソースはレイヤーによって所有されるため、シャットダウンすると逆の依存関係順序で解放されます。
5. HTTPサーバーがバインドする 127.0.0.1 ポート 0 に接続すると、オペレーティング システムが空きポートを選択します。
6. 公衆衛生ルートが調査されている。それが答えて初めて、 {"event":"ready","port":N} 標準出力に書き込まれます。
7. シェルはその行を最大 60 秒待機し、サイドカーを最大 1 回再起動します。 WebView は最大 125 秒待機します get_sidecar_endpoint、接続します。

認証モデル

署名付きトークンは発行者とともに HS256 を使用します cadcamfun。取り消されたトークンは次のように検証されます invalid、不明なトークンまたは偽造されたトークンは取り消しによって無視されます。署名シークレットはインストールごとに 1 回生成され、データ ディレクトリに保存されるため、再起動前に発行されたリンクは再起動後も検証されます。

データディレクトリに存在するもの

サイドカーが停止している間、または WAL にチェックポイントを作成したシャットダウン後に、ディレクトリ全体をバックアップします。コピーのみ cadcamfun.db サイドカーの実行中に、WAL ファイル内に残っている最近の書き込みが失われる可能性があります。

レディラインを捉えた

CADCAMFUN_TOKEN=t CADCAMFUN_DATA_DIR="$(mktemp -d)" \
CADCAMFUN_MIGRATIONS_DIR="$PWD/packages/db/drizzle" \
CADCAMFUN_AI_HOST=direct CADCAMFUN_AI_OFFLINE=true \
bun --no-env-file apps/sidecar/src/main.ts
# stdout: {"event":"ready","port":43461}

ポートは、起動するたびにオペレーティング システムによって選択されます。この行は、移行とレイヤーの準備が完了した後の最初の stdout 出力であるため、これを見たクライアントはすぐに API を呼び出すことができます。標準入力は開いたままにしておきます。標準入力を閉じるとシャットダウン信号になります。

3Dで