Sidecar

Responsabilidades de tempo de execução

O sidecar é o backend do Bun compartilhado pelas integrações de desktop e desenvolvimento local. Ele abre SQLite, fornece repositórios e serviços de domínio, atende a API HTTP definida pelo esquema e hospeda assistente e integração de fluxo de trabalho. O shell Tauri inicia o binário empacotado e descobre sua porta atribuída a partir de um evento de inicialização legível por máquina.

apps/sidecar/src/layers.ts compõe a API servida, manipuladores, autorização, repositórios e serviços. Provedores opcionais, como checkout pago e modelos de IA, são configurados por meio de seus serviços; sua ausência não transforma um registro de banco de dados em uma integração externa funcional.

Protocolo de processo e desligamento

O servidor HTTP principal liga apenas 127.0.0.1, com porta 0 então o sistema operacional escolhe uma porta disponível. O tempo limite de inatividade do HTTP é desativado para permitir que uma longa chamada do assistente permaneça silenciosa entre eventos transmitidos. O desligamento normal do HTTP é configurado para 500 milissegundos antes que a finalização do escopo continue.

Depois que a investigação de saúde pública da API for bem-sucedida, o processo imprimirá um evento pronto no stdout. A falha na inicialização imprime um evento de erro e define um código de saída com falha. Os logs operacionais vão para stderr como JSON; stdout é reservado para o protocolo do processo pai.

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

Uma mensagem stdin terminada em nova linha com event: "shutdown", fechamento stdin, SIGINT ou SIGTERM libera o escopo do servidor. Mensagens pai malformadas são ignoradas e uma linha incompleta superdimensionada é descartada. Os finalizadores interrompem os serviços próprios e verificam/fecham o SQLite. O encerramento somente de interrupção é relatado como uma saída limpa.

Configuração necessária

AppConfigService lê a configuração do processo uma vez em apps/sidecar/src/config.ts. CADCAMFUN_TOKEN é o token de portador do aplicativo necessário e CADCAMFUN_DATA_DIR é o diretório de dados do aplicativo necessário. O caminho do banco de dados é <dataDir>/cadcamfun.db. CADCAMFUN_MIGRATIONS_DIR é opcional e fornece a pasta de migração SQL; sem ele, a camada de banco de dados não aplica migrações de aplicativos.

A área de trabalho fornece configuração de inicialização. Para desenvolvimento direto, forneça esses nomes de configuração no shell de inicialização e execute o script inicial do pacote na raiz do repositório:

bun run --filter @cadcamfun/sidecar start

O pacote sidecar define start e typecheck roteiros. A compilação binária empacotada pertence aos scripts de lançamento do repositório, em vez de um pacote secundário build comando.

Configuração opcional

• CADCAMFUN_APP_URL define a base para links de autenticação; CADCAMFUN_DEBUG_LINKS permite retornar links mágicos/de redefinição de depuração e o padrão é falso.
• CADCAMFUN_AI_HOST é nikcli (padrão; o bate-papo é executado por meio do host de conversa incorporado) ou direct (somente AI SDK). CADCAMFUN_AI_OFFLINE (booleano, padrão falso) desativa o caminho de rede opcional do catálogo de modelos. CADCAMFUN_AI_MINIMAX_BASE_URL substitui o endpoint do MiniMax.
• STRIPE_SECRET_KEY habilita o provedor Stripe; STRIPE_PRICE_BASIC, STRIPE_PRICE_PRO, e STRIPE_PRICE_ENTERPRISE fornecer preços de planos pagos. STRIPE_WEBHOOK_SECRET é necessário para verificação de webhook assinado.
• CRON_SECRET fornece o segredo da rota cron; sem ele, o aplicativo local pode chamar essa rota sem um segredo cron adicional. ADMIN_EMAIL é uma verificação de identidade de administrador legado; por padrão, o perfil local é o administrador de sua própria instalação.
• OTEL_EXPORTER_OTLP_ENDPOINT habilita a exportação de telemetria OTLP configurada. Sem um ponto final, a exportação de telemetria externa está desativada.

Todos esses nomes são lidos em um só lugar, AppConfigService; o token e a chave secreta Stripe são mantidos como valores editados para que não apareçam nos logs. As chaves do provedor de IA são gerenciadas por meio da API de credenciais e do arquivo de credenciais dedicado. Eles não são lidos como configurações de ambiente de chave de API do fornecedor por AppConfigService.

Acesso HTTP e descoberta de API

O sidecar publica /api/openapi.json por seu contrato servido e usa middleware de portador em grupos protegidos. Um segundo cabeçalho de sessão opcional escolhe a conta atuante. O perfil local é criado ou reutilizado em local@cadcamfun.local, mantendo a instalação utilizável sem login na conta.

CORS admite tauri://localhost, HTTP/HTTPS tauri.localhoste origens HTTP localhost ou 127.0.0.1 com uma porta opcional. Outras origens não recebem nenhum cabeçalho de resposta de origem permitida. CORS é uma política do navegador; o middleware do portador continua sendo o controle de acesso para rotas protegidas.

Os grupos atendidos abrangem recursos de design, geração e verificação de fabricação, CAD exato, bibliotecas, custos, IA, VCS/fluxos de trabalho, eventos, controles complementares, identidade, organizações, notificações, arquivos, plug-ins, faturamento, análises, lista de espera, MCP e estado local. Consulte o documento OpenAPI em execução para obter detalhes do método e da carga útil.

O cabeçalho da conta atuante é x-session-token. Sem ele, ou com um token que não é verificado como token de sessão para um usuário existente, as solicitações atuam como o perfil local (src/http/authorization.ts).

Organização de origem

main.ts inicia o servidor com escopo definido e o protocolo pai. config.ts configuração de suprimentos, layers.ts dependências de fios, startup.ts compartilha a prontidão e a porta de loopback, shutdown.ts lê mensagens de desligamento pai e observability.ts configura telemetria opcional.

http/ mapeia solicitações validadas para serviços. repos/ mapeia recursos para consultas Drizzle e regras de acesso a recursos. services/ coordena o comportamento entre recursos e plugins/ contém implementações de host de trabalho e de inicialização do navegador.

Grupos de manipuladores

Os manipuladores são agrupados por recursos: projetos, desenhos, componentes, percursos da ferramenta de ferramentas e extras, o gerador de percursos da ferramenta, CAD exato, configurações de materiais/ferramentas/máquinas e suas rotas de armazenamento, biblioteca, custos, arquivos, organizações, notificações, usuário/autenticação, faturamento, análises, lista de espera, MCP, serviços de aplicativos diversos, estado de valor-chave, IA, VCS, eventos e gerenciamento complementar.

entity-io.ts compartilha auxiliares de importação/exportação de entidade. authorization.ts aplica credenciais de ponte de aplicativo e escopo. A carga declarada de um manipulador já passou pela decodificação do esquema; a validação de nível de serviço ainda verifica referências, propriedade, consistência de evidências e restrições de domínio.

Composição do serviço de domínio

Os serviços de IA fornecem desenhos e ações CAM, inspeção paramétrica/exata, contexto do projeto, memória, diários de trabalho e ferramentas de plug-in. cam-program.ts executa novamente solicitações de fabricação capturadas e valida evidências nativas durante salvamentos. Os serviços de histórico aplicam instantâneos, regras de ramificação protegida, transporte GitHub e execução de fluxo de trabalho.

Outros serviços possuem armazenamento de arquivos, cálculos de custos, perfil local e estado do usuário ativo, assinatura/revogação de token, credenciais de ponte, pagamentos, notificações, eventos ao vivo e ciclo de vida complementar. As camadas de efeito possuem seus recursos, então o desligamento os libera em ordem de dependência.

Limite do repositório

Repositórios usam o compartilhado Database.query serviço para persistência e falhas de armazenamento digitadas. Eles decodificam o JSON armazenado e impõem acesso específico ao recurso ou fornecem auxiliares de autorização. Os manipuladores HTTP traduzem falhas de domínio/armazenamento em erros de resposta declarados; cálculos de geometria permanecem @cadcamfun/core.

Integração de plug-ins

O host geral do trabalhador está em plugins/host.ts. O serviço de plug-in do assistente de produção carrega explicitamente habilitado ai:tool extensões do diretório de plug-ins do aplicativo. O instalador ZIP do navegador e a API de inicialização usam seus próprios caminhos de manifesto e armazenamento. Ver Plug-ins antes de selecionar um formato de extensão ou assumir que um recurso está conectado.

Gateway HTTPS complementar

O gateway complementar é um ouvinte HTTPS opcional separado que pode retomar uma configuração habilitada anteriormente. Ele vincula IPv4 para clientes da rede, apresenta um certificado gerado retido sob <dataDir>/companione usa tokens de dispositivo revogáveis com escopo definido. O emparelhamento fornece uma impressão digital de certificado para que o transporte móvel possa fixar a área de trabalho.

O gateway verifica uma lista de permissões de rota explícita e encaminha solicitações admitidas para a API de loopback com o token do aplicativo. Um telefone emparelhado nunca recebe esse token de aplicativo. A lista de permissões exclui administração de credenciais, instalação de plugins, gerenciamento de arquivos e cobrança. A revogação de um dispositivo ou a desativação do gateway remove seu acesso à rede.

Prontidão e diagnóstico

O evento pronto significa que a investigação de integridade HTTP local foi bem-sucedida após a construção da camada do servidor. Isso não significa que um provedor modelo aceitou uma solicitação, que o checkout esteja configurado ou que todos os serviços de rede opcionais estejam acessíveis. Diagnosticar esses serviços por meio de seus próprios endpoints de status e resultados.

Para um erro de inicialização, retenha a mensagem do protocolo e os eventos stderr relevantes, verifique a configuração e as migrações e inspecione a acessibilidade do diretório de dados. Nunca cole o token do portador de inicialização ou o conteúdo da credencial do provedor na saída de diagnóstico.

Propriedade de dados

Os dados persistentes incluem o banco de dados SQLite e backups de migração, armazenamento de arquivos, credencial/estado de configuração de IA, segredo de autenticação e registros de revogação, ativos de plug-in e certificados complementares. Proteja todo o diretório de dados do aplicativo ao fazer backup ou transferir uma instalação. O sidecar possui vida útil da conexão; os clientes não possuem o identificador SQLite nem a emissão do token de portador principal.

Lançar uma instância local descartável

Execute esses comandos na raiz do repositório em um terminal dedicado. O diretório é novo, o token é gerado localmente sem imprimi-lo, as migrações são explícitas e o modo AI direto/offline evita a importação do host de conversação incorporado para esta verificação de inicialização. openssl fornece o token de inicialização aleatório neste exemplo 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

Leia a porta do evento pronto em vez de assumir um número fixo. Mantenha o stdin aberto enquanto o serviço é executado; a tubulação de uma fonte de entrada já finalizada solicita seu desligamento. Use SIGTERM ou o protocolo de desligamento para liberar o banco de dados. O diretório descartável permanece disponível para inspeção após a saída.

Com uma URL de conexão e seu token já disponível no shell do cliente, compare a atividade pública com o acesso protegido:

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.

Logs e telemetria opcional

Os logs Stderr JSON e os eventos stdout ready/error têm consumidores diferentes. Um iniciador deve analisar linhas stdout completas e encaminhar ou reter stderr separadamente. Uma solicitação que falha após a prontidão é um erro de aplicativo, não um segundo evento de inicialização.

Quando OTEL_EXPORTER_OTLP_ENDPOINT está configurado, ObservabilityLive configura lotes para períodos/logs e exportação de métricas periódicas. Ele anexa /v1/traces, /v1/metrics, e /v1/logs à base do coletor fornecida após remover as barras finais. Forneça uma base coletora como http://collector:4318, em vez de um URL de sinal já com sufixo.

O nome do serviço de recurso é cadcamfun-sidecar e sua versão vem da configuração do aplicativo. As configurações padrão do ambiente de recursos OpenTelemetry são tratadas pelo SDK. A exportação de rede é opcional, enquanto o stderr local permanece disponível quando nenhum coletor está configurado.

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

Identifique o limite com falha

Os testes de ciclo de vida do processo real cobrem EOF, uma linha JSON de desligamento dividido e SIGTERM, depois reiniciam o mesmo diretório de dados e verificam os projetos persistentes. Eles também inspecionam o WAL após a saída. Isto estabelece o comportamento do ciclo de vida do processo de origem; o shell empacotado e a entrega específica da máquina ainda exigem sua própria validação.

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

Sequência de inicialização em detalhes

1. O shell gera um token de inicialização de 32 bytes aleatórios, codificados em hexadecimal como 64 caracteres, e inicia o sidecar com CADCAMFUN_TOKEN, CADCAMFUN_DATA_DIR, e CADCAMFUN_MIGRATIONS_DIR.
2. AppConfigService lê todas as configurações uma vez. Uma configuração necessária ausente falha na inicialização com um error evento.
3. A camada do banco de dados é aberta <dataDir>/cadcamfun.db, ativa o modo WAL e chaves estrangeiras e aplica migrações do diretório de migrações.
4. As camadas são compostas: banco de dados, depois repositórios, depois serviços e, por fim, manipuladores HTTP. Cada recurso pertence a uma camada, portanto, o shutdown o libera em ordem inversa de dependência.
5. O servidor HTTP se liga 127.0.0.1 na porta 0 e o sistema operacional escolhe uma porta livre.
6. A rota da saúde pública é investigada. Só depois de responder é {"event":"ready","port":N} escrito em stdout.
7. O shell aguarda até 60 segundos por essa linha e reinicia o sidecar no máximo uma vez. A webview aguarda até 125 segundos para get_sidecar_endpointe depois conecta.

Modelo de autenticação

Tokens assinados usam HS256 com o emissor cadcamfun. Tokens revogados são verificados como invalid, e tokens desconhecidos ou forjados são ignorados pela revogação. O segredo de assinatura é gerado uma vez por instalação e armazenado no diretório de dados, portanto, os links emitidos antes da reinicialização ainda serão verificados posteriormente.

O que reside no diretório de dados

Faça backup de todo o diretório enquanto o sidecar estiver parado ou após um desligamento que tenha verificado o WAL. Copiando apenas cadcamfun.db enquanto as execuções do sidecar podem perder gravações recentes que ainda estão no arquivo WAL.

A linha pronta, capturada

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}

A porta é escolhida pelo sistema operacional a cada inicialização. A linha é a primeira saída stdout após as migrações e camadas estarem prontas, para que um cliente que a veja possa chamar a API imediatamente. Mantenha o stdin aberto: fechá-lo é o sinal de desligamento.

Em 3D