Sidecar

Responsabilità di runtime

Il sidecar è il backend Bun condiviso dalle integrazioni desktop e di sviluppo locale. Apre SQLite, fornisce repository e servizi di dominio, serve l'API HTTP definita dallo schema e ospita l'assistente e l'integrazione del flusso di lavoro. La shell Tauri avvia il pacchetto binario e scopre la porta assegnata da un evento di avvio leggibile dalla macchina.

apps/sidecar/src/layers.ts compone l'API servita, i gestori, l'autorizzazione, i repository e i servizi. I fornitori opzionali come checkout a pagamento e modelli AI sono configurati attraverso i loro servizi; la loro assenza non trasforma un record del database in un'integrazione esterna funzionante.

Protocollo di processo e di spegnimento

Si collega solo il server HTTP principale 127.0.0.1, con porto 0 quindi il sistema operativo sceglie una porta disponibile. Il timeout di inattività HTTP è disabilitato per consentire a una lunga chiamata all'assistente di rimanere silenziosa tra gli eventi trasmessi in streaming. L'arresto HTTP regolare è configurato per 500 millisecondi prima che la finalizzazione dell'ambito continui.

Dopo che l'analisi della salute pubblica dell'API ha avuto esito positivo, il processo stampa un evento pronto su stdout. L'errore di avvio stampa un evento di errore e imposta un codice di uscita non riuscito. I log operativi vanno a stderr come JSON; stdout è riservato per il protocollo del processo genitore.

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

Un messaggio stdin con terminazione a nuova riga con event: "shutdown", chiusura stdin, SIGINT o SIGTERM rilasciano l'ambito del server. I messaggi principali con formato errato vengono ignorati e una riga incompleta di grandi dimensioni viene scartata. I finalizzatori interrompono i servizi di proprietà e checkpoint/chiudono SQLite. La terminazione con sola interruzione viene segnalata come un'uscita pulita.

Configurazione richiesta

AppConfigService legge la configurazione del processo una volta dentro apps/sidecar/src/config.ts. CADCAMFUN_TOKEN è il token portatore dell'applicazione richiesto e CADCAMFUN_DATA_DIR è la directory dei dati dell'applicazione richiesta. Il percorso del database è <dataDir>/cadcamfun.db. CADCAMFUN_MIGRATIONS_DIR è facoltativo e fornisce la cartella di migrazione SQL; senza di esso il livello del database non applica le migrazioni delle applicazioni.

Il desktop fornisce la configurazione di avvio. Per lo sviluppo diretto, fornisci i nomi di configurazione nella shell di avvio ed esegui lo script di avvio del pacchetto dalla root del repository:

bun run --filter @cadcamfun/sidecar start

Il pacchetto sidecar definisce start e typecheck script. La compilazione binaria in pacchetti è di proprietà degli script di rilascio del repository, piuttosto che di un pacchetto sidecar build comando.

Configurazione opzionale

• CADCAMFUN_APP_URL imposta la base per i collegamenti di autenticazione; CADCAMFUN_DEBUG_LINKS consente di restituire collegamenti debug/magic e il valore predefinito è false.
• CADCAMFUN_AI_HOST è nikcli (impostazione predefinita; la chat viene eseguita tramite l'host di conversazione incorporato) o direct (Solo SDK AI). CADCAMFUN_AI_OFFLINE (booleano, default false) disabilita il percorso di rete opzionale del catalogo modelli. CADCAMFUN_AI_MINIMAX_BASE_URL sovrascrive l'endpoint di MiniMax.
• STRIPE_SECRET_KEY abilita il fornitore Stripe; STRIPE_PRICE_BASIC, STRIPE_PRICE_PRO, e STRIPE_PRICE_ENTERPRISE fornire i prezzi dei piani a pagamento. STRIPE_WEBHOOK_SECRET è richiesto per la verifica del webhook firmato.
• CRON_SECRET fornisce il segreto del percorso cron; senza di esso l'applicazione locale può chiamare quella rotta senza un segreto cron aggiuntivo. ADMIN_EMAIL è un controllo dell'identità dell'amministratore legacy; per impostazione predefinita il profilo locale è l'amministratore della propria installazione.
• OTEL_EXPORTER_OTLP_ENDPOINT abilita l'esportazione della telemetria OTLP configurata. Senza un endpoint, l'esportazione della telemetria esterna è disattivata.

Tutti questi nomi vengono letti in un unico posto, AppConfigService; il token e la chiave segreta Stripe vengono conservati come valori redatti in modo che non vengano visualizzati nei log. Le chiavi del provider AI vengono gestite tramite l'API delle credenziali e il file delle credenziali dedicato. Non vengono lette come impostazioni dell'ambiente della chiave API del fornitore AppConfigService.

Accesso HTTP e rilevamento API

Il sidecar pubblica /api/openapi.json per il contratto servito e utilizza middleware portante su gruppi protetti. Una seconda intestazione di sessione opzionale sceglie l'account agente. Il profilo locale viene creato o riutilizzato in local@cadcamfun.local, mantenendo l'installazione utilizzabile senza l'accesso all'account.

Lo ammette il CORS tauri://localhost, HTTP/HTTPS tauri.localhoste origini HTTP localhost o 127.0.0.1 con una porta opzionale. Altre origini non ricevono alcuna intestazione di risposta di origine consentita. CORS è una politica del browser; il middleware portante rimane il controllo degli accessi per i percorsi protetti.

I gruppi serviti coprono risorse di progettazione, generazione e verifica della produzione, CAD esatto, librerie, costi, intelligenza artificiale, VCS/flussi di lavoro, eventi, controlli complementari, identità, organizzazioni, notifiche, file, plug-in, fatturazione, analisi, lista d'attesa, MCP e stato locale. Consultare il documento OpenAPI in esecuzione per i dettagli sul metodo e sul carico utile.

L'intestazione del conto corrente è x-session-token. Senza di esso, o con un token che non viene verificato come token di sessione per un utente esistente, le richieste fungono da profilo locale (src/http/authorization.ts).

Organizzazione delle fonti

main.ts avvia il server con ambito e il protocollo principale. config.ts configurazione delle forniture, layers.ts dipendenze dei cavi, startup.ts condivide la disponibilità e la porta di loopback, shutdown.ts legge i messaggi di arresto del genitore e observability.ts configura la telemetria opzionale.

http/ mappa le richieste convalidate ai servizi. repos/ associa le risorse alle query Drizzle e alle regole di accesso alle risorse. services/ coordina il comportamento tra risorse e plugins/ contiene implementazioni di bootstrap dell'host lavoratore e del browser.

Gruppi di gestori

I gestori sono raggruppati per risorsa: progetti, disegni, componenti, percorsi utensile ed extra, generatore di percorsi utensile, CAD esatto, configurazioni di materiali/strumenti/macchine e relativi percorsi di archiviazione, libreria, costi, file, organizzazioni, notifiche, utente/autorizzazione, fatturazione, analisi, lista d'attesa, MCP, servizi applicativi vari, stato valore-chiave, AI, VCS, eventi e gestione complementare.

entity-io.ts condivide gli aiutanti di importazione/esportazione di entità. authorization.ts applica le credenziali dell'applicazione e del bridge con ambito. Il payload dichiarato di un gestore ha già superato la decodifica dello schema; la convalida del livello di servizio controlla comunque i riferimenti, la proprietà, la coerenza delle prove e i vincoli del dominio.

Composizione del servizio di dominio

I servizi di intelligenza artificiale forniscono azioni di disegno e CAM, ispezione parametrica/esatta, contesto di progetto, memoria, diari dei lavoratori e strumenti di plug-in. cam-program.ts riesegue le richieste di produzione acquisite e convalida le prove native durante i salvataggi. I servizi di cronologia applicano snapshot, regole di ramo protetto, trasporto GitHub ed esecuzione del flusso di lavoro.

Altri servizi possiedono archiviazione di file, calcoli dei costi, profilo locale e stato dell'utente agente, firma/revoca di token, credenziali bridge, pagamenti, notifiche, eventi live e ciclo di vita complementare. I livelli di effetti possiedono le proprie risorse, quindi lo spegnimento le rilascia in ordine di dipendenza.

Confine del repository

I repository utilizzano il file shared Database.query servizio per la persistenza e gli errori di archiviazione digitati. Decodificano il JSON archiviato e impongono l'accesso specifico alle risorse o forniscono assistenti per l'autorizzazione. I gestori HTTP traducono gli errori di dominio/archiviazione negli errori di risposta dichiarati; i calcoli della geometria rimangono @cadcamfun/core.

Integrazione dei plugin

L'ospite lavoratore generale è presente plugins/host.ts. Il servizio plug-in dell'assistente di produzione viene caricato esplicitamente abilitato ai:tool estensioni dalla directory dei plugin dell'applicazione. Il programma di installazione ZIP del browser e l'API bootstrap utilizzano i propri percorsi manifest e di archiviazione. Vedere Plugin prima di selezionare un formato di estensione o presupporre che una funzionalità sia cablata.

Gateway HTTPS complementare

Il gateway complementare è un listener HTTPS con consenso esplicito separato che può ripristinare un'impostazione precedentemente abilitata. Associa IPv4 per i client di rete, presenta un certificato generato e conservato in <dataDir>/companione utilizza token di dispositivo revocabili con ambito. L'accoppiamento fornisce un'impronta digitale del certificato in modo che il trasporto mobile possa bloccare il desktop.

Il gateway controlla un elenco consentito di instradamenti espliciti e inoltra le richieste ammesse all'API di loopback con il token dell'applicazione. Un telefono accoppiato non riceve mai il token dell'applicazione. L'elenco consentiti esclude l'amministrazione delle credenziali, l'installazione dei plug-in, la gestione dei file e la fatturazione. La revoca di un dispositivo o la disattivazione del gateway ne rimuove l'accesso alla rete.

Prontezza e diagnostica

L'evento ready indica che l'analisi dell'integrità HTTP locale ha avuto esito positivo dopo la costruzione del livello server. Ciò non significa che il fornitore del modello abbia accettato una richiesta, che il pagamento sia configurato o che tutti i servizi di rete opzionali siano raggiungibili. Diagnosticare tali servizi attraverso il loro stato e gli endpoint dei risultati.

In caso di errore di avvio, conserva il messaggio del protocollo e gli eventi stderr rilevanti, controlla la configurazione e le migrazioni e controlla l'accessibilità della directory dei dati. Non incollare mai il token di connessione del lancio o il contenuto delle credenziali del provider nell'output diagnostico.

Proprietà dei dati

I dati persistenti includono il database SQLite e i backup di migrazione, l'archiviazione di file, lo stato delle credenziali/configurazione AI, i segreti di autenticazione e i record di revoca, le risorse dei plug-in e i certificati complementari. Proteggi l'intera directory dei dati dell'applicazione durante il backup o il trasferimento di un'installazione. Il sidecar possiede la durata della connessione; i client non possiedono né l'handle SQLite né l'emissione del token al portatore principale.

Avvia un'istanza locale usa e getta

Esegui questi comandi nella root del repository in un terminale dedicato. La directory è nuova, il token viene generato localmente senza stamparlo, le migrazioni sono esplicite e la modalità AI diretta/offline evita l'importazione dell'host di conversazione incorporato per questo controllo di avvio. openssl fornisce il token di avvio casuale in questo esempio di 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

Leggi la porta dell'evento pronto anziché assumere un numero fisso. Mantieni stdin aperto mentre il servizio è in esecuzione; la tubazione da una sorgente di ingresso già terminata gli chiede di spegnersi. Utilizzare SIGTERM o il protocollo di shutdown per rilasciare il database. La directory usa e getta rimane disponibile per l'ispezione dopo l'uscita.

Con un URL di connessione e il relativo token già disponibili nella shell del client, confronta l'attività pubblica con l'accesso protetto:

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"

Fonte: apps/sidecar/src/main.ts, config.ts, shutdown.ts, e test/process.test.ts.

Registri e telemetria opzionale

I log JSON Stderr e gli eventi di errore/pronto stdout hanno consumatori diversi. Un launcher dovrebbe analizzare le linee stdout complete e inoltrare o conservare stderr separatamente. Una richiesta che non riesce dopo essere pronta è un errore dell'applicazione, non un secondo evento di avvio.

Quando OTEL_EXPORTER_OTLP_ENDPOINT è configurato, ObservabilityLive imposta il raggruppamento per intervalli/log e l'esportazione periodica delle metriche. Si aggiunge /v1/traces, /v1/metrics, e /v1/logs alla base del collettore in dotazione dopo aver rimosso le barre finali. Fornire una base da collezione come http://collector:4318, anziché un URL del segnale già con suffisso.

Il nome del servizio risorsa è cadcamfun-sidecar e la sua versione deriva dalla configurazione dell'applicazione. Le impostazioni standard dell'ambiente delle risorse OpenTelemetry vengono gestite dall'SDK. L'esportazione in rete è facoltativa, mentre lo stderr locale rimane disponibile quando non è configurato alcun raccoglitore.

Fonte: apps/sidecar/src/observability.ts e main.ts.

Identificare il confine fallito

I test del ciclo di vita del processo reale coprono EOF, una linea JSON di arresto diviso e SIGTERM, quindi riavviano la stessa directory di dati e verificano i progetti persistenti. Ispezionano anche il WAL dopo l'uscita. Ciò stabilisce il comportamento del ciclo di vita del processo di origine; la shell in pacchetto e la consegna specifica della macchina richiedono ancora la propria convalida.

Fonte: apps/sidecar/test/process.test.ts, src/http/authorization.ts, src/layers.ts, e src/services/companion.ts.

Sequenza di avvio in dettaglio

1. La shell genera un token di lancio di 32 byte casuali, codificati esadecimali come 64 caratteri e avvia il sidecar con CADCAMFUN_TOKEN, CADCAMFUN_DATA_DIR, e CADCAMFUN_MIGRATIONS_DIR.
2. AppConfigService legge tutte le impostazioni una volta. Un'impostazione richiesta mancante non riesce all'avvio con un error evento.
3. Si apre il livello del database <dataDir>/cadcamfun.db, abilita la modalità WAL e le chiavi esterne e applica le migrazioni dalla directory delle migrazioni.
4. I livelli sono composti: database, quindi repository, quindi servizi, quindi gestori HTTP. Ogni risorsa è di proprietà di un livello, quindi l'arresto la rilascia in ordine di dipendenza inversa.
5. Il server HTTP si lega 127.0.0.1 sulla porta 0 e il sistema operativo sceglie una porta libera.
6. Si indaga sulla strada della sanità pubblica. Solo dopo aver risposto lo è {"event":"ready","port":N} scritto su stdout.
7. La shell attende fino a 60 secondi per quella linea e riavvia il sidecar al massimo una volta. La visualizzazione web attende fino a 125 secondi per get_sidecar_endpoint, quindi si connette.

Modello di autenticazione

I token firmati utilizzano HS256 con l'emittente cadcamfun. I token revocati vengono verificati come invalide i token sconosciuti o contraffatti vengono ignorati dalla revoca. Il segreto della firma viene generato una volta per installazione e archiviato nella directory dei dati, pertanto i collegamenti emessi prima del riavvio vengono comunque verificati in seguito.

Ciò che vive nella directory dei dati

Eseguire il backup dell'intera directory mentre il sidecar è fermo o dopo un arresto che ha bloccato il WAL. Solo copia cadcamfun.db mentre le esecuzioni del sidecar possono perdere le scritture recenti ancora nel file WAL.

La linea pronta, catturata

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}

La porta viene scelta dal sistema operativo ad ogni avvio. La riga è il primo output stdout dopo che le migrazioni e i livelli sono pronti, quindi un client che la vede può chiamare immediatamente l'API. Mantieni stdin aperto: chiudendolo è il segnale di spegnimento.

Nel 3D