Sidecar

Responsabilidades en tiempo de ejecución

El sidecar es el backend de Bun compartido por las integraciones de desarrollo local y de escritorio. Abre SQLite, proporciona repositorios y servicios de dominio, sirve la API HTTP definida por esquema y aloja asistente e integración de flujo de trabajo. El shell Tauri inicia el binario empaquetado y descubre su puerto asignado a partir de un evento de inicio legible por máquina.

apps/sidecar/src/layers.ts compone la API servida, los controladores, la autorización, los repositorios y los servicios. Los proveedores opcionales, como el pago de pago y los modelos de IA, se configuran a través de sus servicios; su ausencia no convierte un registro de base de datos en una integración externa funcional.

Protocolo de proceso y apagado

El servidor HTTP principal solo se vincula 127.0.0.1, con puerto 0 entonces el sistema operativo elige un puerto disponible. El tiempo de espera de inactividad de HTTP está deshabilitado para permitir que una llamada prolongada al asistente permanezca en silencio entre eventos transmitidos. El cierre HTTP ordenado se configura durante 500 milisegundos antes de que continúe la finalización del alcance.

Una vez que la prueba de salud pública de la API tiene éxito, el proceso imprime un evento listo en la salida estándar. El error de inicio imprime un evento de error y establece un código de salida fallido. Los registros operativos van a stderr como JSON; stdout está reservado para el protocolo del proceso principal.

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

Un mensaje estándar terminado en nueva línea con event: "shutdown", el cierre estándar, SIGINT o SIGTERM libera el alcance del servidor. Los mensajes principales con formato incorrecto se ignoran y se descarta una línea incompleta de gran tamaño. Los finalizadores detienen los servicios propios y controlan/cierran SQLite. La terminación de sólo interrupción se informa como una salida limpia.

Configuración requerida

AppConfigService lee la configuración del proceso una vez en apps/sidecar/src/config.ts. CADCAMFUN_TOKEN es el token portador de la aplicación requerido y CADCAMFUN_DATA_DIR es el directorio de datos de la aplicación requerido. La ruta de la base de datos es <dataDir>/cadcamfun.db. CADCAMFUN_MIGRATIONS_DIR es opcional y proporciona la carpeta de migración de SQL; sin él, la capa de base de datos no aplica las migraciones de aplicaciones.

El escritorio proporciona la configuración de inicio. Para el desarrollo directo, proporcione esos nombres de configuración en el shell de inicio y ejecute el script de inicio del paquete desde la raíz del repositorio:

bun run --filter @cadcamfun/sidecar start

El paquete sidecar define start y typecheck guiones. La compilación binaria empaquetada es propiedad de los scripts de lanzamiento del repositorio, en lugar de un paquete complementario. build dominio.

Configuración opcional

• CADCAMFUN_APP_URL establece la base para los enlaces de autenticación; CADCAMFUN_DEBUG_LINKS permite devolver enlaces mágicos/restablecidos de depuración y el valor predeterminado es falso.
• CADCAMFUN_AI_HOST es nikcli (predeterminado; el chat se ejecuta a través del host de conversación integrado) o direct (Solo AI SDK). CADCAMFUN_AI_OFFLINE (booleano, predeterminado falso) deshabilita la ruta de red opcional del catálogo de modelos. CADCAMFUN_AI_MINIMAX_BASE_URL anula el punto final de MiniMax.
• STRIPE_SECRET_KEY habilita el proveedor de Stripe; STRIPE_PRICE_BASIC, STRIPE_PRICE_PRO, y STRIPE_PRICE_ENTERPRISE ofrecer precios de planes pagos. STRIPE_WEBHOOK_SECRET es necesario para la verificación del webhook firmado.
• CRON_SECRET proporciona el secreto de ruta cron; sin él, la aplicación local puede llamar a esa ruta sin un secreto cron adicional. ADMIN_EMAIL es una verificación de identidad del administrador heredado; por defecto el perfil local es el administrador de su propia instalación.
• OTEL_EXPORTER_OTLP_ENDPOINT habilita la exportación de telemetría OTLP configurada. Sin un punto final, la exportación de telemetría externa está desactivada.

Todos estos nombres se leen en un solo lugar, AppConfigService; el token y la clave secreta de Stripe se mantienen como valores redactados para que no aparezcan en los registros. Las claves del proveedor de IA se administran a través de la API de credenciales y el archivo de credenciales dedicado. No los lee como configuración del entorno de clave API del proveedor. AppConfigService.

Acceso HTTP y descubrimiento de API

El sidecar publica /api/openapi.json para su contrato servido y utiliza middleware portador en grupos protegidos. Un segundo encabezado de sesión opcional elige la cuenta actual. El perfil local se crea o se reutiliza en local@cadcamfun.local, manteniendo la instalación utilizable sin iniciar sesión en la cuenta.

CORS admite tauri://localhost, HTTP/HTTPS tauri.localhosty HTTP localhost o orígenes 127.0.0.1 con un puerto opcional. Otros orígenes no reciben ningún encabezado de respuesta de origen permitido. CORS es una política del navegador; el middleware portador sigue siendo el control de acceso a las rutas protegidas.

Los grupos atendidos cubren recursos de diseño, generación y verificación de fabricación, CAD exacto, bibliotecas, costos, IA, VCS/flujos de trabajo, eventos, controles complementarios, identidad, organizaciones, notificaciones, archivos, complementos, facturación, análisis, lista de espera, MCP y estado local. Consulte el documento OpenAPI en ejecución para conocer los detalles del método y la carga útil.

El encabezado de la cuenta en funciones es x-session-token. Sin él, o con un token que no se verifica como token de sesión para un usuario existente, las solicitudes actúan como el perfil local (src/http/authorization.ts).

Organización fuente

main.ts inicia el servidor con ámbito y el protocolo principal. config.ts configuración de suministros, layers.ts dependencias de cables, startup.ts comparte la preparación y el puerto loopback, shutdown.ts lee los mensajes de cierre de los padres y observability.ts configura la telemetría opcional.

http/ asigna solicitudes validadas a servicios. repos/ asigna recursos a consultas de Drizzle y reglas de acceso a recursos. services/ coordina el comportamiento entre recursos, y plugins/ contiene implementaciones de arranque de navegador y host de trabajo.

Grupos de controladores

Los controladores se agrupan por recursos: proyectos, dibujos, componentes, rutas de herramientas y extras, el generador de rutas de herramientas, CAD exacto, materiales/herramientas/configuraciones de máquinas y sus rutas de almacenamiento, biblioteca, costos, archivos, organizaciones, notificaciones, usuario/autenticación, facturación, análisis, lista de espera, MCP, servicios de aplicaciones diversas, estado clave-valor, IA, VCS, eventos y administración complementaria.

entity-io.ts comparte ayudantes de importación/exportación de entidades. authorization.ts aplica las credenciales de aplicación y puente de ámbito. La carga útil declarada de un controlador ya pasó la decodificación del esquema; La validación de nivel de servicio aún verifica las referencias, la propiedad, la coherencia de la evidencia y las restricciones de dominio.

Composición del servicio de dominio

Los servicios de IA proporcionan acciones de dibujo y CAM, inspección paramétrica/exacta, contexto del proyecto, memoria, diarios de trabajadores y herramientas complementarias. cam-program.ts vuelve a ejecutar solicitudes de fabricación capturadas y valida la evidencia nativa durante los guardados. Los servicios de historial aplican instantáneas, reglas de rama protegida, transporte de GitHub y ejecución de flujo de trabajo.

Otros servicios poseen almacenamiento de archivos, cálculos de costos, perfil local y estado de usuario activo, firma/revocación de tokens, credenciales de puente, pagos, notificaciones, eventos en vivo y ciclo de vida complementario. Las capas de efectos poseen sus recursos, por lo que el apagado los libera en orden de dependencia.

Límite del repositorio

Los repositorios utilizan el compartido Database.query servicio para persistencia y fallas de almacenamiento escrito. Decodifican JSON almacenado y aplican el acceso a recursos específicos o proporcionan ayudas de autorización. Los controladores HTTP traducen los errores de dominio/almacenamiento en sus errores de respuesta declarados; los cálculos de geometría permanecen en @cadcamfun/core.

Integración de complementos

El anfitrión general de trabajadores está en plugins/host.ts. El servicio del complemento del asistente de producción se carga explícitamente habilitado ai:tool extensiones del directorio de complementos de la aplicación. El instalador ZIP del navegador y la API de arranque utilizan sus propias rutas de manifiesto y almacenamiento. Ver Complementos antes de seleccionar un formato de extensión o asumir que una capacidad está cableada.

Puerta de enlace HTTPS complementaria

La puerta de enlace complementaria es un oyente HTTPS independiente que puede reanudar una configuración previamente habilitada. Vincula IPv4 para clientes de red, presenta un certificado generado retenido bajo <dataDir>/companiony utiliza tokens de dispositivo revocables con alcance. El emparejamiento proporciona una huella digital de certificado para que el dispositivo móvil pueda fijar el escritorio.

La puerta de enlace verifica una lista de rutas permitidas explícitas y reenvía las solicitudes admitidas a la API de loopback con el token de la aplicación. Un teléfono emparejado nunca recibe ese token de aplicación. La lista de permitidos excluye la administración de credenciales, la instalación de complementos, la administración de archivos y la facturación. Revocar un dispositivo o deshabilitar la puerta de enlace elimina su acceso a la red.

Preparación y diagnóstico.

El evento listo significa que la sonda de estado HTTP local se realizó correctamente después de la construcción de la capa del servidor. No significa que un proveedor modelo haya aceptado una solicitud, que el pago esté configurado o que todos los servicios de red opcionales sean accesibles. Diagnosticar esos servicios a través de su propio estado y puntos finales de resultados.

En caso de error de inicio, conserve el mensaje del protocolo y los eventos stderr relevantes, verifique la configuración y las migraciones e inspeccione la accesibilidad del directorio de datos. Nunca pegue el contenido del token de portador de lanzamiento o de la credencial del proveedor en la salida de diagnóstico.

Propiedad de los datos

Los datos persistentes incluyen la base de datos SQLite y las copias de seguridad de migración, el almacenamiento de archivos, el estado de configuración/credenciales de IA, los registros de revocación y secreto de autenticación, los activos de complementos y los certificados complementarios. Proteja todo el directorio de datos de la aplicación al realizar una copia de seguridad o transferir una instalación. El sidecar posee la vida útil de la conexión; los clientes no poseen ni el identificador de SQLite ni la emisión del token del portador principal.

Lanzar una instancia local desechable

Ejecute estos comandos en la raíz del repositorio en una terminal dedicada. El directorio es nuevo, el token se genera localmente sin imprimirlo, las migraciones son explícitas y el modo AI directo/fuera de línea evita importar el host de conversación integrado para esta verificación de inicio. openssl proporciona el token de inicio aleatorio en este ejemplo 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

Lea el puerto del evento listo en lugar de asumir un número fijo. Mantenga la entrada estándar abierta mientras se ejecuta el servicio; la tubería de una fuente de entrada ya terminada le solicita que se apague. Utilice SIGTERM o el protocolo de apagado para liberar la base de datos. El directorio desechable permanece disponible para su inspección después de la salida.

Con una URL de conexión y su token ya disponibles en el shell del cliente, compare la actividad pública con el acceso 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"

Fuente: apps/sidecar/src/main.ts, config.ts, shutdown.ts, y test/process.test.ts.

Registros y telemetría opcional

Los registros Stderr JSON y los eventos de error/preparación estándar tienen consumidores diferentes. Un lanzador debe analizar líneas estándar completas y reenviar o retener stderr por separado. Una solicitud que falla después de la preparación es un error de aplicación, no un segundo evento de inicio.

Cuando OTEL_EXPORTER_OTLP_ENDPOINT está configurado, ObservabilityLive configura el procesamiento por lotes para tramos/registros y la exportación de métricas periódicas. se agrega /v1/traces, /v1/metrics, y /v1/logs a la base del colector suministrada después de quitar las barras diagonales. Suministrar una base colectora como http://collector:4318, en lugar de una URL de señal que ya tiene el sufijo.

El nombre del servicio de recursos es cadcamfun-sidecar y su versión proviene de la configuración de la aplicación. El SDK maneja la configuración estándar del entorno de recursos de OpenTelemetry. La exportación de red es opcional, mientras que el stderr local permanece disponible cuando no se configura ningún recopilador.

Fuente: apps/sidecar/src/observability.ts y main.ts.

Identificar el límite fallido

Las pruebas del ciclo de vida del proceso real cubren EOF, una línea JSON de cierre dividido y SIGTERM, luego reinician el mismo directorio de datos y verifican los proyectos persistentes. También inspeccionan el WAL después de la salida. Esto establece el comportamiento del ciclo de vida del proceso fuente; La carcasa empaquetada y la entrega específica de la máquina aún requieren su propia validación.

Fuente: apps/sidecar/test/process.test.ts, src/http/authorization.ts, src/layers.ts, y src/services/companion.ts.

Secuencia de inicio en detalle

1. El shell genera un token de lanzamiento de 32 bytes aleatorios, codificados en hexadecimal como 64 caracteres, e inicia el sidecar con CADCAMFUN_TOKEN, CADCAMFUN_DATA_DIR, y CADCAMFUN_MIGRATIONS_DIR.
2. AppConfigService lee todas las configuraciones una vez. Una configuración requerida que falta no permite iniciar con un error evento.
3. Se abre la capa de base de datos. <dataDir>/cadcamfun.db, habilita el modo WAL y las claves externas, y aplica migraciones desde el directorio de migraciones.
4. Las capas se componen: base de datos, luego repositorios, luego servicios y luego controladores HTTP. Cada recurso pertenece a una capa, por lo que el apagado lo libera en orden de dependencia inverso.
5. El servidor HTTP se une 127.0.0.1 en el puerto 0 y el sistema operativo elige un puerto libre.
6. Se investiga la vía de la salud pública. Sólo después de que responda es {"event":"ready","port":N} escrito en salida estándar.
7. El shell espera hasta 60 segundos para esa línea y reinicia el sidecar como máximo una vez. La vista web espera hasta 125 segundos para get_sidecar_endpoint, luego se conecta.

Modelo de autenticación

Los tokens firmados utilizan HS256 con el emisor cadcamfun. Los tokens revocados se verifican como invalidy los tokens desconocidos o falsificados se ignoran mediante la revocación. El secreto de firma se genera una vez por instalación y se almacena en el directorio de datos, por lo que los enlaces emitidos antes de un reinicio aún se verifican después.

¿Qué vive en el directorio de datos?

Haga una copia de seguridad de todo el directorio mientras el sidecar está detenido o después de un apagado que controló el WAL. Sólo copiando cadcamfun.db mientras que las ejecuciones del sidecar pueden perder escrituras recientes que todavía están en el archivo WAL.

La línea lista, 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}

El puerto lo elige el sistema operativo en cada inicio. La línea es la primera salida estándar después de que las migraciones y las capas estén listas, por lo que un cliente que la vea puede llamar a la API inmediatamente. Mantenga stdin abierto: cerrarlo es la señal de apagado.

En 3D