Sidecar

Laufzeitverantwortung

Der Sidecar ist das Bun-Backend, das von den Desktop- und lokalen Entwicklungsintegrationen gemeinsam genutzt wird. Es öffnet SQLite, stellt Repositorys und Domänendienste bereit, bedient die schemadefinierte HTTP-API und hostet den Assistenten und die Workflow-Integration. Die Tauri-Shell startet die gepackte Binärdatei und erkennt den zugewiesenen Port anhand eines maschinenlesbaren Startereignisses.

apps/sidecar/src/layers.ts stellt die bereitgestellte API, Handler, Autorisierung, Repositorys und Dienste zusammen. Optionale Anbieter wie kostenpflichtiger Checkout und KI-Modelle werden über ihre Dienste konfiguriert; Ihr Fehlen verwandelt einen Datenbankeintrag nicht in eine funktionierende externe Integration.

Prozess- und Abschaltprotokoll

Der Haupt-HTTP-Server bindet nur 127.0.0.1, mit Hafen 0 daher wählt das Betriebssystem einen verfügbaren Port aus. Das HTTP-Leerlauf-Timeout ist deaktiviert, damit ein langer Assistentenaufruf zwischen gestreamten Ereignissen stumm bleiben kann. Das ordnungsgemäße Herunterfahren von HTTP ist für 500 Millisekunden konfiguriert, bevor die Bereichsfinalisierung fortgesetzt wird.

Nachdem die öffentliche Gesundheitsprüfung der API erfolgreich war, gibt der Prozess ein Bereit-Ereignis auf stdout aus. Ein Startfehler gibt ein Fehlerereignis aus und legt einen Exit-Code für den Fehler fest. Betriebsprotokolle werden als JSON an stderr gesendet. stdout ist für das übergeordnete Prozessprotokoll reserviert.

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

Eine durch einen Zeilenumbruch beendete Standardnachricht mit event: "shutdown", stdin-Abschluss, SIGINT oder SIGTERM gibt den Serverbereich frei. Fehlerhafte übergeordnete Nachrichten werden ignoriert und eine übergroße unvollständige Zeile wird verworfen. Finalizer stoppen eigene Dienste und prüfen/schließen SQLite. Die ausschließliche Interrupt-Beendigung wird als sauberer Exit gemeldet.

Erforderliche Konfiguration

AppConfigService liest die Prozesskonfiguration einmal ein apps/sidecar/src/config.ts. CADCAMFUN_TOKEN ist das erforderliche Anwendungsträgertoken und CADCAMFUN_DATA_DIR ist das erforderliche Anwendungsdatenverzeichnis. Der Datenbankpfad lautet <dataDir>/cadcamfun.db. CADCAMFUN_MIGRATIONS_DIR ist optional und stellt den SQL-Migrationsordner bereit; Ohne sie führt die Datenbankschicht keine Anwendungsmigrationen durch.

Der Desktop liefert die Startkonfiguration. Geben Sie für die direkte Entwicklung diese Konfigurationsnamen in der Start-Shell an und führen Sie das Startskript des Pakets im Repository-Stammverzeichnis aus:

bun run --filter @cadcamfun/sidecar start

Das Sidecar-Paket definiert start und typecheck skripte. Die gepackte Binärkompilierung ist Eigentum der Repository-Release-Skripte und nicht eines Sidecar-Pakets build befehl.

Optionale Konfiguration

• CADCAMFUN_APP_URL legt die Basis für Authentifizierungslinks fest; CADCAMFUN_DEBUG_LINKS aktiviert die Rückgabe von Debug-Reset-/Magic-Links und ist standardmäßig auf „false“ eingestellt.
• CADCAMFUN_AI_HOST ist nikcli (standard; Chat läuft über den eingebetteten Konversationshost) oder direct (Nur AI SDK). CADCAMFUN_AI_OFFLINE (boolean, Standardwert false) deaktiviert den optionalen Modellkatalog-Netzwerkpfad. CADCAMFUN_AI_MINIMAX_BASE_URL überschreibt den Endpunkt von MiniMax.
• STRIPE_SECRET_KEY aktiviert den Stripe-Anbieter; STRIPE_PRICE_BASIC, STRIPE_PRICE_PRO, und STRIPE_PRICE_ENTERPRISE bereitstellung von kostenpflichtigen Planpreisen. STRIPE_WEBHOOK_SECRET ist für die signierte Webhook-Verifizierung erforderlich.
• CRON_SECRET stellt das Cron-Route-Geheimnis bereit; Ohne sie kann die lokale Anwendung diese Route ohne ein zusätzliches Cron-Geheimnis aufrufen. ADMIN_EMAIL ist eine Legacy-Administrator-Identitätsprüfung; Standardmäßig ist das lokale Profil der Administrator seiner eigenen Installation.
• OTEL_EXPORTER_OTLP_ENDPOINT aktiviert den konfigurierten OTLP-Telemetrieexport. Ohne Endpunkt ist der externe Telemetrieexport deaktiviert.

Alle diese Namen werden an einer Stelle gelesen, AppConfigService; der Token und der geheime Stripe-Schlüssel werden als geschwärzte Werte gespeichert, sodass sie nicht in Protokollen erscheinen. KI-Anbieterschlüssel werden über die Anmeldeinformations-API und eine dedizierte Anmeldeinformationsdatei verwaltet. Sie werden von nicht als API-Schlüsselumgebungseinstellungen des Anbieters gelesen AppConfigService.

HTTP-Zugriff und API-Erkennung

Der Sidecar veröffentlicht /api/openapi.json für seinen bedienten Vertrag und nutzt Träger-Middleware für geschützte Gruppen. Ein zweiter optionaler Sitzungsheader wählt das handelnde Konto aus. Das lokale Profil wird unter erstellt oder wiederverwendet local@cadcamfun.local, sodass die Installation ohne Kontoanmeldung nutzbar bleibt.

CORS gibt zu tauri://localhost, HTTP/HTTPS tauri.localhostund HTTP localhost oder 127.0.0.1 Ursprünge mit einem optionalen Port. Andere Ursprünge erhalten keinen Antwortheader mit zulässigem Ursprung. CORS ist eine Browserrichtlinie; Die Träger-Middleware bleibt die Zugriffskontrolle für geschützte Routen.

Die bedienten Gruppen umfassen Designressourcen, Fertigungsgenerierung und -verifizierung, exaktes CAD, Bibliotheken, Kosten, KI, VCS/Workflows, Ereignisse, Begleitsteuerungen, Identität, Organisationen, Benachrichtigungen, Dateien, Plugins, Abrechnung, Analysen, Warteliste, MCP und lokaler Status. Einzelheiten zur Methode und Nutzlast finden Sie im laufenden OpenAPI-Dokument.

Der Acting-Account-Header lautet x-session-token. Ohne sie oder mit einem Token, das nicht als Sitzungstoken für einen vorhandenen Benutzer verifiziert wird, fungieren Anforderungen als lokales Profil (src/http/authorization.ts).

Quellorganisation

main.ts startet den bereichsbezogenen Server und das übergeordnete Protokoll. config.ts lieferungen Konfiguration, layers.ts drahtabhängigkeiten, startup.ts teilt Bereitschaft und den Loopback-Port, shutdown.ts liest Meldungen zum Herunterfahren des übergeordneten Elements und observability.ts konfiguriert optionale Telemetrie.

http/ ordnet validierte Anfragen Diensten zu. repos/ ordnet Ressourcen Drizzle-Abfragen und Ressourcenzugriffsregeln zu. services/ koordiniert das ressourcenübergreifende Verhalten und plugins/ enthält Worker-Host- und Browser-Bootstrap-Implementierungen.

Handlergruppen

Handler sind nach Ressourcen gruppiert: Projekte, Zeichnungen, Komponenten, Werkzeugwege und Extras, der Werkzeugweggenerator, exaktes CAD, Materialien/Werkzeuge/Maschinenkonfigurationen und ihre Speicherrouten, Bibliothek, Kosten, Dateien, Organisationen, Benachrichtigungen, Benutzer/Authentifizierung, Abrechnung, Analyse, Warteliste, MCP, verschiedene Anwendungsdienste, Schlüsselwertstatus, KI, VCS, Ereignisse und Begleitverwaltung.

entity-io.ts teilt Entitäts-Import-/Export-Helfer. authorization.ts wendet Anwendungs- und bereichsbezogene Bridge-Anmeldeinformationen an. Die deklarierte Nutzlast eines Handlers hat die Schemadekodierung bereits bestanden; Bei der Service-Level-Validierung werden weiterhin Referenzen, Eigentum, Beweiskonsistenz und Domäneneinschränkungen überprüft.

Zusammensetzung des Domänendienstes

KI-Dienste bieten Zeichnungs- und CAM-Aktionen, parametrische/exakte Inspektion, Projektkontext, Speicher, Arbeitstagebücher und Plug-in-Tools. cam-program.ts führt erfasste Fertigungsanforderungen erneut aus und validiert native Beweise beim Speichern. Verlaufsdienste wenden Snapshots, Regeln für geschützte Zweige, GitHub-Transport und Workflow-Ausführung an.

Andere Dienste verfügen über Dateispeicher, Kostenberechnungen, lokales Profil und Status des handelnden Benutzers, Token-Signierung/-Widerruf, Bridge-Anmeldeinformationen, Zahlungen, Benachrichtigungen, Live-Ereignisse und den Lebenszyklus von Begleitern. Effektebenen besitzen ihre Ressourcen, daher werden sie beim Herunterfahren in der Abhängigkeitsreihenfolge freigegeben.

Repository-Grenze

Repositorys verwenden das Shared Database.query dienst für Persistenz und typisierte Speicherfehler. Sie entschlüsseln gespeichertes JSON und erzwingen ressourcenspezifischen Zugriff oder stellen Autorisierungshilfen bereit. HTTP-Handler übersetzen Domänen-/Speicherfehler in ihre deklarierten Antwortfehler; Geometrieberechnungen bleiben erhalten @cadcamfun/core.

Plugin-Integration

Der allgemeine Worker-Host ist da plugins/host.ts. Der Produktionsassistent-Plugin-Dienst wird explizit aktiviert geladen ai:tool erweiterungen aus dem Anwendungs-Plugin-Verzeichnis. Das Browser-ZIP-Installationsprogramm und die Bootstrap-API verwenden ihre eigenen Manifest- und Speicherpfade. Sehen Plugins bevor Sie ein Erweiterungsformat auswählen oder davon ausgehen, dass eine Funktion verkabelt ist.

Begleitendes HTTPS-Gateway

Das Companion-Gateway ist ein separater Opt-in-HTTPS-Listener, der eine zuvor aktivierte Einstellung wieder aufnehmen kann. Es bindet IPv4 für Netzwerk-Clients und stellt ein generiertes Zertifikat bereit, das darunter aufbewahrt wird <dataDir>/companionund verwendet bereichsbezogene, widerrufbare Gerätetoken. Durch das Koppeln wird ein Fingerabdruck des Zertifikats bereitgestellt, damit das Mobilgerät den Desktop anheften kann.

Das Gateway prüft eine explizite Route-Zulassungsliste und leitet zugelassene Anfragen mit dem Anwendungstoken an die Loopback-API weiter. Ein gekoppeltes Telefon erhält dieses Anwendungstoken nie. Die Zulassungsliste schließt die Verwaltung von Anmeldeinformationen, die Plugin-Installation, die Dateiverwaltung und die Abrechnung aus. Durch das Sperren eines Geräts oder das Deaktivieren des Gateways wird dessen Netzwerkzugriff entfernt.

Bereitschaft und Diagnose

Das Ready-Ereignis bedeutet, dass die lokale HTTP-Integritätsprüfung nach dem Aufbau der Serverschicht erfolgreich war. Dies bedeutet nicht, dass ein Modellanbieter eine Anfrage angenommen hat, der Checkout konfiguriert ist oder jeder optionale Netzwerkdienst erreichbar ist. Diagnostizieren Sie diese Dienste anhand ihrer eigenen Status- und Ergebnisendpunkte.

Behalten Sie bei einem Startfehler die Protokollnachricht und die relevanten stderr-Ereignisse bei, überprüfen Sie die Konfiguration und Migrationen und überprüfen Sie die Zugänglichkeit des Datenverzeichnisses. Fügen Sie niemals den Inhalt des Startträgertokens oder der Anbieteranmeldeinformationen in die Diagnoseausgabe ein.

Dateneigentum

Zu den persistenten Daten gehören die SQLite-Datenbank und Migrationssicherungen, Dateispeicher, AI-Anmeldeinformationen/-Konfigurationsstatus, Authentifizierungsgeheimnisse und Sperrdatensätze, Plugin-Assets und Begleitzertifikate. Schützen Sie das gesamte Anwendungsdatenverzeichnis, wenn Sie es sichern oder eine Installation übertragen. Der Sidecar besitzt die Verbindungslebensdauer; Clients besitzen weder das SQLite-Handle noch die Ausgabe des Hauptträgertokens.

Starten Sie eine verfügbare lokale Instanz

Führen Sie diese Befehle im Repository-Stammverzeichnis in einem dedizierten Terminal aus. Das Verzeichnis ist neu, das Token wird lokal generiert, ohne es zu drucken, Migrationen sind explizit und der Direkt-/Offline-KI-Modus vermeidet den Import des eingebetteten Konversationshosts für diese Startprüfung. openssl stellt in diesem Shell-Beispiel das zufällige Starttoken bereit.

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

Lesen Sie den Port des Ready-Ereignisses, anstatt eine feste Nummer anzunehmen. Halten Sie stdin geöffnet, während der Dienst ausgeführt wird. Die Weiterleitung von einer bereits beendeten Eingabequelle fordert zum Herunterfahren auf. Verwenden Sie SIGTERM oder das Shutdown-Protokoll, um die Datenbank freizugeben. Das Einwegverzeichnis bleibt nach dem Beenden zur Einsicht verfügbar.

Da eine Verbindungs-URL und ihr Token bereits in einer Client-Shell verfügbar sind, vergleichen Sie die öffentliche Präsenz mit dem geschützten Zugriff:

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"

Quelle: apps/sidecar/src/main.ts, config.ts, shutdown.ts, und test/process.test.ts.

Protokolle und optionale Telemetrie

Stderr-JSON-Protokolle und stdout-Bereitschafts-/Fehlerereignisse haben unterschiedliche Verbraucher. Ein Launcher sollte vollständige stdout-Zeilen analysieren und stderr separat weiterleiten oder beibehalten. Eine Anforderung, die nach der Bereitschaft fehlschlägt, ist ein Anwendungsfehler und kein zweites Startereignis.

Wann OTEL_EXPORTER_OTLP_ENDPOINT konfiguriert ist, ObservabilityLive richtet die Stapelverarbeitung für Spans/Protokolle und den regelmäßigen Metrikexport ein. Es hängt an /v1/traces, /v1/metrics, und /v1/logs an der mitgelieferten Kollektorbasis befestigen, nachdem die nachlaufenden Schrägstriche entfernt wurden. Stellen Sie einen Kollektorsockel bereit, z http://collector:4318, anstelle einer bereits angehängten Signal-URL.

Der Name des Ressourcendienstes lautet cadcamfun-sidecar und seine Version stammt aus der Anwendungskonfiguration. Die Standardeinstellungen der OpenTelemetry-Ressourcenumgebung werden vom SDK verwaltet. Der Netzwerkexport ist optional, während der lokale stderr verfügbar bleibt, wenn kein Collector konfiguriert ist.

Quelle: apps/sidecar/src/observability.ts und main.ts.

Identifizieren Sie die fehlerhafte Grenze

Die Lebenszyklustests für reale Prozesse umfassen EOF, eine geteilte JSON-Zeile zum Herunterfahren und SIGTERM. Anschließend wird dasselbe Datenverzeichnis neu gestartet und persistente Projekte überprüft. Sie inspizieren auch die WAL nach dem Verlassen. Dadurch wird das Lebenszyklusverhalten des Quellprozesses festgelegt. Für verpackte Shell- und maschinenspezifische Lieferungen ist weiterhin eine eigene Validierung erforderlich.

Quelle: apps/sidecar/test/process.test.ts, src/http/authorization.ts, src/layers.ts, und src/services/companion.ts.

Startsequenz im Detail

1. Die Shell generiert ein Starttoken mit 32 zufälligen Bytes, hexadezimal codiert als 64 Zeichen, und startet den Sidecar mit CADCAMFUN_TOKEN, CADCAMFUN_DATA_DIR, und CADCAMFUN_MIGRATIONS_DIR.
2. AppConfigService liest alle Einstellungen einmal. Eine fehlende erforderliche Einstellung schlägt beim Start mit einer Fehlermeldung fehl error ereignis.
3. Die Datenbankschicht wird geöffnet <dataDir>/cadcamfun.db, aktiviert den WAL-Modus und Fremdschlüssel und wendet Migrationen aus dem Migrationsverzeichnis an.
4. Die Schichten bestehen aus: Datenbank, dann Repositorys, dann Dienste, dann HTTP-Handler. Jede Ressource gehört einer Ebene, daher wird sie beim Herunterfahren in umgekehrter Abhängigkeitsreihenfolge freigegeben.
5. Der HTTP-Server bindet 127.0.0.1 auf Port 0, und das Betriebssystem wählt einen freien Port aus.
6. Der Weg der öffentlichen Gesundheit wird geprüft. Erst nachdem es antwortet {"event":"ready","port":N} auf stdout geschrieben.
7. Die Shell wartet bis zu 60 Sekunden auf diese Zeile und startet den Sidecar höchstens einmal neu. Die Webansicht wartet bis zu 125 Sekunden get_sidecar_endpoint, dann verbindet.

Authentifizierungsmodell

Signierte Token verwenden HS256 mit dem Aussteller cadcamfun. Widerrufene Token werden überprüft als invalid, und unbekannte oder gefälschte Token werden beim Widerruf ignoriert. Das Signaturgeheimnis wird einmal pro Installation generiert und im Datenverzeichnis gespeichert, sodass vor einem Neustart ausgegebene Links auch danach noch gültig sind.

Was befindet sich im Datenverzeichnis?

Sichern Sie das gesamte Verzeichnis, während der Sidecar gestoppt ist oder nach einem Herunterfahren, das einen Prüfpunkt für die WAL verursacht hat. Nur Kopieren cadcamfun.db während die Sidecar-Läufe aktuelle Schreibvorgänge übersehen können, die sich noch in der WAL-Datei befinden.

Die Bereitschaftslinie, erfasst

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}

Der Port wird bei jedem Start vom Betriebssystem ausgewählt. Die Zeile ist die erste Standardausgabe, nachdem Migrationen und Ebenen bereit sind, sodass ein Client, der sie sieht, die API sofort aufrufen kann. Halten Sie stdin geöffnet: Das Schließen ist das Signal zum Herunterfahren.

In 3D