Sidecar

Responsabilités d'exécution

Le sidecar est le backend Bun partagé par les intégrations de bureau et de développement local. Il ouvre SQLite, fournit des référentiels et des services de domaine, sert l'API HTTP définie par le schéma et héberge l'assistant et l'intégration du flux de travail. Le shell Tauri démarre le binaire packagé et découvre le port qui lui est attribué à partir d'un événement de démarrage lisible par machine.

apps/sidecar/src/layers.ts compose l'API servie, les gestionnaires, l'autorisation, les référentiels et les services. Les fournisseurs facultatifs tels que le paiement payant et les modèles d'IA sont configurés via leurs services ; leur absence ne transforme pas un enregistrement de base de données en une intégration externe fonctionnelle.

Protocole de processus et d'arrêt

Le serveur HTTP principal se lie uniquement 127.0.0.1, avec port 0 le système d'exploitation choisit donc un port disponible. Le délai d'inactivité HTTP est désactivé pour permettre à un long appel d'assistant de rester silencieux entre les événements diffusés en streaming. L'arrêt HTTP progressif est configuré pendant 500 millisecondes avant que la finalisation de l'étendue ne se poursuive.

Une fois la sonde de santé publique de l'API réussie, le processus imprime un événement prêt sur la sortie standard. L'échec du démarrage imprime un événement d'erreur et définit un code de sortie défaillant. Les journaux opérationnels sont envoyés vers stderr au format JSON ; stdout est réservé au protocole du processus parent.

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

Un message stdin terminé par une nouvelle ligne avec event: "shutdown", la fermeture stdin, SIGINT ou SIGTERM libère la portée du serveur. Les messages parents mal formés sont ignorés et une ligne incomplète surdimensionnée est supprimée. Les finaliseurs arrêtent les services détenus et pointent/ferment SQLite. La terminaison par interruption uniquement est signalée comme une sortie propre.

Configuration requise

AppConfigService lit la configuration du processus une fois entré apps/sidecar/src/config.ts. CADCAMFUN_TOKEN est le jeton de support d'application requis et CADCAMFUN_DATA_DIR est le répertoire de données d'application requis. Le chemin de la base de données est <dataDir>/cadcamfun.db. CADCAMFUN_MIGRATIONS_DIR est facultatif et fournit le dossier de migration SQL ; sans cela, la couche base de données n'applique pas les migrations d'applications.

Le bureau fournit la configuration de lancement. Pour le développement direct, fournissez ces noms de configuration dans le shell de lancement et exécutez le script de démarrage du package à partir de la racine du référentiel :

bun run --filter @cadcamfun/sidecar start

Le package sidecar définit start et typecheck scripts. La compilation binaire packagée appartient aux scripts de version du référentiel, plutôt qu'à un package sidecar build commande.

Configuration facultative

• CADCAMFUN_APP_URL définit la base des liens d'authentification ; CADCAMFUN_DEBUG_LINKS permet de renvoyer les liens de réinitialisation/magique du débogage et la valeur par défaut est false.
• CADCAMFUN_AI_HOST est nikcli (par défaut ; le chat s'exécute via l'hôte de conversation intégré) ou direct (SDK IA uniquement). CADCAMFUN_AI_OFFLINE (booléen, false par défaut) désactive le chemin réseau facultatif du catalogue de modèles. CADCAMFUN_AI_MINIMAX_BASE_URL remplace le point de terminaison de MiniMax.
• STRIPE_SECRET_KEY active le fournisseur Stripe ; STRIPE_PRICE_BASIC, STRIPE_PRICE_PRO, et STRIPE_PRICE_ENTERPRISE fournir des prix de forfait payants. STRIPE_WEBHOOK_SECRET est requis pour la vérification du webhook signé.
• CRON_SECRET fournit le secret de la route cron ; sans cela, l'application locale peut appeler cette route sans secret cron supplémentaire. ADMIN_EMAIL est une vérification d'identité d'administrateur héritée ; par défaut le profil local est l'administrateur de sa propre installation.
• OTEL_EXPORTER_OTLP_ENDPOINT active l’exportation de télémétrie OTLP configurée. Sans point de terminaison, l’exportation de télémétrie externe est désactivée.

Tous ces noms sont lus au même endroit, AppConfigService; le jeton et la clé secrète Stripe sont conservés sous forme de valeurs expurgées afin qu'ils n'apparaissent pas dans les journaux. Les clés du fournisseur d’IA sont gérées via l’API d’informations d’identification et le fichier d’informations d’identification dédié. Ils ne sont pas lus en tant que paramètres d'environnement de clé API du fournisseur par AppConfigService.

Accès HTTP et découverte d'API

Le sidecar publie /api/openapi.json pour son contrat servi et utilise un middleware support sur les groupes protégés. Un deuxième en-tête de session facultatif choisit le compte actif. Le profil local est créé ou réutilisé sous local@cadcamfun.local, gardant l'installation utilisable sans connexion au compte.

Le CORS admet tauri://localhost, HTTP/HTTPS tauri.localhost, et HTTP localhost ou 127.0.0.1 origines avec un port facultatif. Les autres origines ne reçoivent aucun en-tête de réponse d’origine autorisée. CORS est une politique de navigateur ; le middleware support reste le contrôle d'accès aux routes protégées.

Les groupes servis couvrent les ressources de conception, la génération et la vérification de la fabrication, la CAO exacte, les bibliothèques, les coûts, l'IA, les VCS/workflows, les événements, les contrôles associés, l'identité, les organisations, les notifications, les fichiers, les plugins, la facturation, les analyses, la liste d'attente, le MCP et l'état local. Consultez le document OpenAPI en cours d’exécution pour plus de détails sur la méthode et la charge utile.

L'en-tête du compte intérimaire est x-session-token. Sans cela, ou avec un jeton qui ne se vérifie pas comme jeton de session pour un utilisateur existant, les requêtes font office de profil local (src/http/authorization.ts).

Organisation source

main.ts lance le serveur étendu et le protocole parent. config.ts configuration des fournitures, layers.ts dépendances de fils, startup.ts partage la préparation et le port de bouclage, shutdown.ts lit les messages d'arrêt des parents, et observability.ts configure la télémétrie facultative.

http/ mappe les demandes validées aux services. repos/ mappe les ressources aux requêtes Drizzle et aux règles d'accès aux ressources. services/ coordonne le comportement entre les ressources, et plugins/ contient les implémentations d'hôte de travail et d'amorçage du navigateur.

Groupes de gestionnaires

Les gestionnaires sont regroupés par ressource : projets, dessins, composants, parcours d'outils et extras, générateur de parcours d'outils, CAO exacte, matériaux/outils/configurations de machines et leurs itinéraires de stockage, bibliothèque, coûts, fichiers, organisations, notifications, utilisateur/authentification, facturation, analyses, liste d'attente, MCP, divers services d'application, état clé-valeur, IA, VCS, événements et gestion des compagnons.

entity-io.ts partage les aides à l'import/export de l'entité. authorization.ts applique les informations d'identification de l'application et du pont étendu. La charge utile déclarée par un gestionnaire a déjà réussi le décodage du schéma ; la validation au niveau du service vérifie toujours les références, la propriété, la cohérence des preuves et les contraintes de domaine.

Composition du service de domaine

Les services d'IA fournissent des actions de dessin et de FAO, une inspection paramétrique/exacte, le contexte du projet, la mémoire, les journaux des travailleurs et des outils de plug-in. cam-program.ts réexécute les demandes de fabrication capturées et valide les preuves natives lors des sauvegardes. Les services d'historique appliquent des instantanés, des règles de branche protégée, le transport GitHub et l'exécution de flux de travail.

D'autres services possèdent le stockage de fichiers, les calculs de coûts, le profil local et l'état de l'utilisateur actif, la signature/révocation des jetons, les informations d'identification du pont, les paiements, les notifications, les événements en direct et le cycle de vie du compagnon. Les couches d'effets possèdent leurs ressources, donc l'arrêt les libère dans l'ordre de dépendance.

Limite du référentiel

Les référentiels utilisent le partage Database.query service pour la persistance et les échecs de stockage typés. Ils décodent le JSON stocké et appliquent un accès spécifique aux ressources ou fournissent des aides à l'autorisation. Les gestionnaires HTTP traduisent les échecs de domaine/stockage en erreurs de réponse déclarées ; les calculs de géométrie restent en place @cadcamfun/core.

Intégration de plugins

L'hôte général des travailleurs est en plugins/host.ts. Le service de plug-in de l'assistant de production se charge explicitement activé ai:tool extensions du répertoire du plugin de l'application. Le programme d'installation ZIP du navigateur et l'API d'amorçage utilisent leurs propres chemins de manifeste et de stockage. Voir Plugins avant de sélectionner un format d’extension ou de supposer qu’une fonctionnalité est câblée.

Passerelle HTTPS compagnon

La passerelle compagnon est un écouteur HTTPS opt-in distinct qui peut reprendre un paramètre précédemment activé. Il lie IPv4 pour les clients du réseau, présente un certificat généré conservé sous <dataDir>/companionet utilise des jetons de périphérique révocables étendus. Le couplage fournit une empreinte digitale de certificat afin que le transport mobile puisse épingler le bureau.

La passerelle vérifie une liste d'autorisation de route explicite et transmet les demandes admises à l'API de bouclage avec le jeton d'application. Un téléphone couplé ne reçoit jamais ce jeton d'application. La liste verte exclut l'administration des informations d'identification, l'installation du plugin, la gestion des fichiers et la facturation. La révocation d'un appareil ou la désactivation de la passerelle supprime son accès au réseau.

Préparation et diagnostic

L'événement ready signifie que la sonde d'intégrité HTTP locale a réussi après la construction de la couche serveur. Cela ne signifie pas qu'un fournisseur de modèles a accepté une demande, que le paiement est configuré ou que tous les services réseau facultatifs sont accessibles. Diagnostiquez ces services via leur propre statut et leurs propres points de terminaison.

En cas d'erreur de démarrage, conservez le message de protocole et les événements stderr pertinents, vérifiez la configuration et les migrations, et inspectez l'accessibilité du répertoire de données. Ne collez jamais le contenu du jeton du porteur de lancement ou des informations d’identification du fournisseur dans la sortie de diagnostic.

Propriété des données

Les données persistantes incluent la base de données SQLite et les sauvegardes de migration, le stockage de fichiers, l'état des informations d'identification/de configuration de l'IA, les enregistrements de secret d'authentification et de révocation, les actifs du plug-in et les certificats associés. Protégez l'intégralité du répertoire des données de l'application lors de sa sauvegarde ou du transfert d'une installation. Le sidecar possède la durée de vie de la connexion ; les clients ne possèdent ni le handle SQLite ni l'émission du jeton du porteur principal.

Lancer une instance locale jetable

Exécutez ces commandes à la racine du référentiel dans un terminal dédié. Le répertoire est nouveau, le token est généré localement sans l'imprimer, les migrations sont explicites et le mode IA direct/hors ligne évite d'importer l'hôte de conversation intégré pour cette vérification de démarrage. openssl fournit le jeton de lancement aléatoire dans cet exemple de shell.

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

Lisez le port de l'événement prêt plutôt que de supposer un numéro fixe. Gardez stdin ouvert pendant l'exécution du service ; la tuyauterie provenant d'une source d'entrée déjà terminée lui demande de s'arrêter. Utilisez SIGTERM ou le protocole d'arrêt pour libérer la base de données. Le répertoire jetable reste disponible pour inspection après la sortie.

Avec une URL de connexion et son token déjà disponibles dans un shell client, comparez l'activité publique avec l'accès protégé :

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"

Source: apps/sidecar/src/main.ts, config.ts, shutdown.ts, et test/process.test.ts.

Journaux et télémétrie en option

Les journaux Stderr JSON et les événements stdout ready/error ont des consommateurs différents. Un lanceur doit analyser les lignes stdout complètes et transmettre ou conserver stderr séparément. Une demande qui échoue une fois prête est une erreur d’application et non un deuxième événement de démarrage.

Quand OTEL_EXPORTER_OTLP_ENDPOINT est configuré, ObservabilityLive configure le traitement par lots pour les travées/journaux et l'exportation périodique des métriques. Il ajoute /v1/traces, /v1/metrics, et /v1/logs à la base du collecteur fourni après avoir retiré les barres obliques finales. Fournir une base de collecteur telle que http://collector:4318, plutôt qu'une URL de signal déjà suffixée.

Le nom du service de ressources est cadcamfun-sidecar et sa version provient de la configuration de l'application. Les paramètres d’environnement de ressources OpenTelemetry standard sont gérés par le SDK. L'exportation réseau est facultative, tandis que le stderr local reste disponible lorsqu'aucun collecteur n'est configuré.

Source: apps/sidecar/src/observability.ts et main.ts.

Identifier la limite défaillante

Les tests de cycle de vie des processus réels couvrent EOF, une ligne JSON d'arrêt fractionné et SIGTERM, puis redémarrent le même répertoire de données et vérifient les projets persistants. Ils inspectent également le WAL après la sortie. Cela établit le comportement du cycle de vie du processus source ; La coque emballée et la livraison spécifique à la machine nécessitent toujours leur propre validation.

Source: apps/sidecar/test/process.test.ts, src/http/authorization.ts, src/layers.ts, et src/services/companion.ts.

Séquence de démarrage en détail

1. Le shell génère un jeton de lancement de 32 octets aléatoires, codés en hexadécimal sous forme de 64 caractères, et démarre le sidecar avec CADCAMFUN_TOKEN, CADCAMFUN_DATA_DIR, et CADCAMFUN_MIGRATIONS_DIR.
2. AppConfigService lit tous les paramètres une fois. Un paramètre obligatoire manquant fait échouer le démarrage avec un error événement.
3. La couche de base de données s'ouvre <dataDir>/cadcamfun.db, active le mode WAL et les clés étrangères, et applique les migrations à partir du répertoire migrations.
4. Les couches sont composées : base de données, puis référentiels, puis services, puis gestionnaires HTTP. Chaque ressource appartient à une couche, donc l'arrêt la libère dans l'ordre de dépendance inverse.
5. Le serveur HTTP lie 127.0.0.1 sur le port 0 et le système d'exploitation choisit un port libre.
6. La voie de la santé publique est sondée. Ce n'est qu'après avoir répondu {"event":"ready","port":N} écrit sur la sortie standard.
7. Le shell attend jusqu'à 60 secondes pour cette ligne et redémarre le sidecar au maximum une fois. La vue Web attend jusqu'à 125 secondes pendant get_sidecar_endpoint, puis se connecte.

Modèle d'authentification

Les jetons signés utilisent HS256 avec l'émetteur cadcamfun. Les jetons révoqués sont vérifiés comme invalid, et les jetons inconnus ou falsifiés sont ignorés par la révocation. Le secret de signature est généré une fois par installation et stocké dans le répertoire de données, de sorte que les liens émis avant un redémarrage sont toujours vérifiés par la suite.

Ce qui se trouve dans le répertoire de données

Sauvegardez l'intégralité du répertoire pendant que le sidecar est arrêté ou après un arrêt qui a vérifié le WAL. Copie uniquement cadcamfun.db tandis que les exécutions sidecar peuvent manquer des écritures récentes qui sont toujours dans le fichier WAL.

La ligne prête, capturée

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}

Le port est choisi par le système d'exploitation à chaque démarrage. La ligne est la première sortie standard une fois les migrations et les couches prêtes, donc un client qui la voit peut appeler l'API immédiatement. Gardez stdin ouvert : sa fermeture est le signal d'arrêt.

En 3D