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.
• Rejeter les configurations de démarrage non sûres ou invalides : liaison non-loopback sans token, --require-auth sans token, --allow-origin '*' 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 (allowOriginCors sur l’allowlist mutable -> hostAllowlist -> access log -> bearerAuth -> rate limit -> JSON parser -> telemetry -> 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 et server.ts) :

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 encodés en base64url lorsque cette sélection est vide. Les intégrateurs directs et les invocations sans ce flag désactivé par défaut ne génèrent pas de token.

1. Résoudre et tronquer le token depuis opts.token ou QWEN_SERVER_TOKEN ; cela évite qu’un saut de ligne final provenant de cat token.txt ne rompe silencieusement la comparaison bearer.
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 : non-loopback sans token est refusé ; --require-auth sans token est refusé.
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 : --allow-origin '*' nécessite un token ; 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 échouent fermement. 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 — les liaisons non-loopback nécessitent --allow-origin pour les XHRs du shell.
• 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