Serve Runtime

Overview

packages/cli/src/serve/ est la couche de démarrage pour qwen serve. Il traduit les flags CLI en ServeOptions, valide la configuration de démarrage, construit l’application Express, connecte les middlewares, enregistre les routes, expose les fournisseurs de pré-vérification/statut de l’hôte du daemon, maintient l’anneau d’audit des permissions, et gère la séquence d’arrêt progressif en deux phases. Le travail orienté HTTP se trouve dans cette couche ; le travail orienté ACP se trouve une couche en dessous dans @qwen-code/acp-bridge (voir 03-acp-bridge.md).

Responsibilities

• Analyser et valider ServeOptions : adresse d’écoute, authentification, workspace, limites de sessions / connexions, budget / pool MCP, CORS, timeouts d’inactivité des prompts / SSE / sessions, rate limit, et toggles associés.
• Canonicaliser le workspace principal exactement une fois, et canonicaliser chaque --workspace répété avant d’enregistrer les runtimes de session. La forme canonique principale est partagée par /capabilities.workspaceCwd, le fallback POST /session, et le bridge principal.
• Résoudre le bearer : --token, puis QWEN_SERVER_TOKEN, puis — lorsqu’aucune source n’est présente et que le --hostname demandé est non-loopback (le littéral localhost étant résolu en premier) — un bearer éphémère généré de 128 bits en base64url (22 caractères) affiché une seule fois au démarrage. Les orthographes loopback ne génèrent jamais de token et conservent le mode fiable sans token sauf si --require-auth est défini. La génération se base sur l’orthographe tandis que le refus au démarrage lit l’adresse résolue, ce qui laisse deux dérogations : un localhost qui se résout en non-loopback ne génère jamais de token, et ne démarre que si une source de token a été résolue (Refusing to bind … sinon) ; et un nom non littéral qui se résout en loopback génère un token, perdant le mode fiable sans token afin que son bearer n’imprime que le token.
• Rejeter les configurations de démarrage non sûres ou invalides : une liaison non-loopback dont la source de token est explicitement vide, --require-auth sur une liaison loopback sans token, un --allow-origin HTTP(S) wildcard ou non-loopback sur une liaison loopback sans token, mcpBudgetMode='enforce' sans mcpClientBudget positif, un --workspace inexistant ou n’étant pas un répertoire, et des valeurs de timeout ou de rate-limit invalides.
• Construire la factory WorkspaceFileSystem, le publisher d’audit des permissions, le DaemonStatusProvider, et l’acp-bridge.
• Construire l’application Express, connecter les middlewares (suppression de l’Origin loopback -> access log -> capture du trace-id entrant -> hostAllowlist -> suppression de l’Origin same-origin distante -> allowOriginCors sur l’allowlist mutable d’origines -> /health pré-auth -> assets Web Shell pré-auth -> webhooks de canal -> bearerAuth -> rate limit -> parseur JSON -> télémétrie -> mutationGate par route), et monter les routes de session, CRUD de workspace, fichier, authentification device-flow, vote de permission, et HTTP ACP. (Le mur inconditionnel denyBrowserOriginCors ne subsiste que dans l’app de bootstrap, run-qwen-serve.ts.)
• Lier le port d’écoute et enregistrer les gestionnaires de signaux.
• Exécuter l’arrêt en deux phases sur SIGINT/SIGTERM ; forcer la sortie sur un second signal.

Architecture

Entrée : runQwenServe(opts, deps) dans packages/cli/src/serve/run-qwen-serve.ts. Retourne un RunHandle ({ url, port, close, ... }).

Factory d’application : createServeApp(opts, getPort, deps) dans packages/cli/src/serve/server.ts. Construit l’Application Express. Les intégrateurs directs et les tests l’appellent sans le wrapper de bootstrap.

Registre de capacités : SERVE_CAPABILITY_REGISTRY dans packages/cli/src/serve/capabilities.ts. Chaque tag a une version since et des modes optionnels. Les tags conditionnels sont omis lorsque leur prédicat de déploiement ou d’exécution est faux ; le registre et la carte de prédicats sont la source de référence. Voir 11-capabilities-versioning.md.

Middleware (packages/cli/src/serve/auth.ts, server.ts, server/self-origin.ts, et server/access-log.ts) :

L’app de bootstrap qui répond aux requêtes pendant la fenêtre à froid (createBootstrapServeApp dans run-qwen-serve.ts) exécute une chaîne plus courte dans cet ordre : suppression de l’Origin loopback -> hostAllowlist -> suppression de l’Origin same-origin distante -> le mur CORS (allowOriginCors lorsque --allow-origin est défini, sinon le denyBrowserOriginCors inconditionnel) -> /health pré-auth sur une liaison loopback ordinaire -> bearerAuth -> les routes avec gate /health, /capabilities, et /daemon/status. Elle n’installe aucun log d’accès, donc seules les requêtes qu’elle répond elle-même — /health, /capabilities, et /daemon/status — ne sont pas journalisées. Le wrapper délégant (createDelegatingServeApp) se place devant avec sa propre gate bearer : tout autre chemin de la fenêtre à froid démarre le runtime et est dispatché vers l’app runtime, qui le journalise, avec durationMs mesuré depuis ce hand-off plutôt que depuis le début visible client. Avec --open, l’app runtime répond directement, donc il n’y a pas de fenêtre à froid du tout.

Sous-systèmes :

Imports du package ACP bridge :

• Les primitives d’event-bus sont importées depuis @qwen-code/acp-bridge/eventBus.
• Les primitives de statut sont importées depuis @qwen-code/acp-bridge/status.
• serve/acp-session-bridge.ts reste comme façade de compatibilité locale au CLI pour la surface de bridge plus large.

Flow

Séquence de démarrage

Avant que runQwenServe() ne démarre cette séquence, le mode CLI-only --open-with-auth valide l’éligibilité loopback/Web Shell et remplit ServeOptions.token avec le token configuré sélectionné, ou avec 32 octets aléatoires (un bearer de 256 bits) encodés en base64url lorsque cette sélection est vide. Cette valeur générée est un token configuré ordinaire pour toutes les étapes ci-dessous — c’est pourquoi --require-auth --open-with-auth démarre — et c’est un générateur séparé du bearer éphémère non-loopback de l’étape 1. Les intégrateurs directs qui appellent createServeApp eux-mêmes ne génèrent jamais de token.

1. Résoudre le token depuis opts.token ou QWEN_SERVER_TOKEN, tronqué afin qu’un saut de ligne final provenant de cat token.txt ne rompe silencieusement la comparaison bearer. Lorsque le --hostname demandé est non-loopback (le littéral localhost résolu une première fois) et qu’aucune source n’est présente, générer un bearer éphémère de 128 bits (16 octets) sous forme de 22 caractères base64url au lieu de refuser ; il est affiché une seule fois par le quickstart distant après listen() et change à chaque redémarrage. Les orthographes loopback ne génèrent jamais, afin de conserver le mode fiable sans token. Une source explicitement vide (--token '', ou QWEN_SERVER_TOKEN défini à une valeur vide ou uniquement des espaces) n’est pas “absente”, donc elle supprime toujours la génération — mais la vacuité ne décide du token résolu que dans un seul sens : un --token vide masque une valeur d’env définie et résout à aucun token, tandis qu’une env vide résout à aucun token uniquement quand --token n’est pas passé (un --token non vide l’emporte quand même) ; dans les deux cas, une liaison non-loopback sans token résolu échoue encore aux gardes ci-dessous.
2. Garde contre les fautes de frappe du hostname : --hostname localhost:4170 génère une erreur et suggère --port.
3. Pré-vérification de l’authentification : une liaison non-loopback sans token résolu est refusée — accessible via une source explicitement vide, ou via une liaison localhost dont la résolution unique atterrit hors loopback (la génération dépend de l’orthographe, donc rien n’a été généré ici) ; --require-auth refuse sur une liaison sans token, ce qui après l’étape 1 signifie une liaison loopback sans source configurée. Les gardes --allow-origin HTTP(S) wildcard et non-loopback lisent le même token résolu, donc sur une liaison non-loopback le bearer généré les satisfait et ces refus sont également limités au loopback.
4. Validation du workspace : chemin absolu, existe, répertoire. EACCES / EPERM sont encapsulés pour pointer vers le flag.
5. Canonicaliser le workspace : canonicalizeWorkspace(rawWorkspace) exécute realpathSync.native une fois et alimente /capabilities, le fallback POST /session, et le bridge.
6. Validation du budget MCP : entier positif ; enforce nécessite un budget.
7. Inférence du toggle du pool MCP : l’env parent QWEN_SERVE_NO_MCP_POOL=1 rend mcpPoolActive=false, donc les capacités omettent honnêtement mcp_workspace_pool et mcp_pool_restart.
8. Validation CORS / timeout / rate-limit : les valeurs --allow-origin HTTP(S) wildcard et non-loopback nécessitent un token résolu (voir l’étape 3 pour la raison pour laquelle ces refus sont limités au loopback) ; les valeurs de prompt, writer, channel idle, session idle, reaper, et fenêtre de rate-limit échouent rapidement si elles sont invalides.
9. childEnvOverrides par handle : passer QWEN_SERVE_MCP_CLIENT_BUDGET et QWEN_SERVE_MCP_BUDGET_MODE à l’enfant ACP via BridgeOptions.childEnvOverrides au lieu de muter process.env.
10. Charger settings.json une seule fois : lire context.fileName, policy.permissionStrategy, et policy.consensusQuorum. Les fichiers corrompus reviennent aux valeurs par défaut. validatePolicyConfig() vérifie policy.* par rapport à SERVE_CAPABILITY_REGISTRY.permission_mediation.modes ; les stratégies inconnues ou un consensusQuorum non positif lèvent InvalidPolicyConfigError. Un quorum défini sous une stratégie non-consensus journalise un avertissement sur stderr.
11. Allouer PermissionAuditRing (512 entrées).
12. Construire fsFactory : runQwenServe a par défaut trusted: true ; les appelants directs de createServeApp ont par défaut trusted: false et avertissent une fois.
13. createHttpAcpBridge, voir 03-acp-bridge.md.
14. createServeApp assemble Express.
15. Créer et lier au cycle de vie le serveur HTTP(S) avant l’écoute, puis appeler server.listen(port, hostname) et résoudre le getPort() réel pour l’allowlist d’hôtes. La propriété Conversations ne peut pas démarrer tant que cet écouteur et les restantes gates de démarrage de l’hôte ne sont pas prêts.
16. Enregistrer les gestionnaires SIGINT / SIGTERM pour l’arrêt progressif via le cycle de vie partagé de l’application.

Arrêt progressif

1. Sceller l’admission et commencer tous les drainages au premier signal :
   • Supprimer le registre device-flow et annuler les flux en attente.
   • bridge.shutdown() marque chaque canal isDying = true, envoie une fermeture progressive à l’stdin de chaque enfant ACP, attend KILL_HARD_DEADLINE_MS (10s) par canal, puis appelle channel.kill() si nécessaire.
2. Fermer l’écouteur pendant que les drainages de l’application et de l’hôte s’exécutent :
   • server.close() arrête d’accepter les nouvelles connexions et laisse les requêtes en cours se terminer.
   • SHUTDOWN_FORCE_CLOSE_MS (5s) déclenche server.closeAllConnections().
   • Un second délai de 2s escalade à nouveau si nécessaire.
3. Libérer la propriété Conversations uniquement après une preuve d’arrêt positive de l’écouteur, du travail local de l’application, du travail possédé par l’hôte, du nettoyage de la découverte Live et des drainages du runtime. Toute preuve incomplète rejette l’arrêt au lieu de permettre un handoff non sûr.
4. Second signal pendant la sortie :
   • bridge.killAllSync() + process.exit(1) pour éviter que des enfants orphelins ne bloquent la sortie du daemon.

État et cycle de vie

RunHandle expose :

• url : URL d’écoute résolue, après la résolution du port éphémère.
• port : port réel, y compris la résolution de 0.
• close() : arrêt programmatique pour les intégrateurs et les tests.

Appeler createServeApp directement retourne seulement une Application. Un intégrateur qui a besoin de Live/Conversations doit créer le serveur Node réel, appeler getServeAppLifecycle(app).bindServer(server) avant son premier listen(), et attendre lifecycle.close() pendant l’arrêt. Sans liaison, les routes ordinaires restent disponibles mais Live/Conversations sont en fail closed. Appeler server.close() brut déclenche le nettoyage piloté par les événements, mais l’intégrateur doit tout de même attendre lifecycle.close() pour observer les échecs de drainage ou de libération de propriété.

Dépendances

Configuration

Mises en garde et limites connues

• Un appel direct à createServeApp sans deps.fsFactory ou deps.bridge utilise par défaut trusted: false ; l’ACP côté agent writeTextFile rejette la requête avec untrusted_workspace. L’avertissement n’est affiché qu’une seule fois.
• L’app runtime exécute allowOriginCors sur l’allowlist mutable ; les valeurs Origin sans correspondance reçoivent l’enveloppe de refus 403 (le mur inconditionnel denyBrowserOriginCors ne subsiste que dans l’app de bootstrap). Le Web Shell loopback fonctionne car un autre middleware supprime d’abord les valeurs same-origin loopback correspondantes ; sur une liaison non-loopback avec un token, les XHRs same-origin du shell sont authentifiées par bearer et leur Origin est supprimé avant le mur, donc elles n’ont pas besoin de --allow-origin. Trois cas nécessitent encore une entrée dans l’allowlist : les upgrades WebSocket (terminal, voix), un front proxy à terminaison TLS dont l’origine https ne correspond jamais au socket plain, et tout intermédiaire HTTP plain qui réécrit l’en-tête Host — le proxy_set_header Host $proxy_host par défaut de nginx et l’Ingress k8s le font tous les deux. La traduction de port seule n’a besoin de rien sur une liaison non-loopback (docker -p 8080:4170) : la vérification compare Origin au Host transmis normalisé uniquement et ne consulte jamais le port d’écoute (seuls les ports par défaut de schéma :80/:443 sont supprimés ; un port non par défaut doit y survivre tel quel). Sur la liaison loopback par défaut, ce n’est pas le cas : l’allowlist Host anti-DNS-rebinding n’accepte que le propre port du daemon, donc un tunnel avec traduction de port (ssh -L 8080:localhost:4170) est rejeté avec 403 Invalid Host header pour chaque requête, y compris le document shell, et --allow-origin ne peut pas passer outre — transmettez le même port ou liez en non-loopback. Le remède pour les cas WebSocket et à terminaison TLS est --allow-origin <origin> ; un intermédiaire qui réécrit Host peut à la place être configuré pour transmettre Host tel quel — ce qui ne peut pas aider une fois que TLS se termine au proxy, car le schéma est lu depuis le propre socket du daemon.
• Ordre des body-parsers : les routes utilisant mutate({ strict: true }) retournent 401 seulement après express.json(). Le pire cas est --max-connections × express.json({limit: '10mb'}), ce qui peut aller jusqu’à environ 2,5 Go de mémoire transitoire sur un listener loopback saturé ; ce compromis est intentionnel.
• Plusieurs démons dans un même processus doivent utiliser des childEnvOverrides par handle ; la mutation de process.env crée des conditions de course car defaultSpawnChannelFactory prend un snapshot de l’environnement au moment du spawn.

Références

• packages/cli/src/serve/run-qwen-serve.ts (amorçage, validation au démarrage, arrêt propre)
• packages/cli/src/serve/server.ts (createServeApp(), assemblage des middlewares et des routes)
• packages/cli/src/serve/auth.ts (CORS, allowlist des hôtes, authentification bearer, contrôle des mutations)
• packages/cli/src/serve/rate-limit.ts (limite de débit HTTP par niveau)
• packages/cli/src/serve/capabilities.ts (registre des capacités et annonce conditionnelle)
• packages/cli/src/serve/types.ts (ServeOptions, CapabilitiesEnvelope)
• packages/cli/src/serve/daemon-status-provider.ts
• packages/cli/src/serve/permission-audit.ts
• Tickets : #3803 , #4175