Cap'n Web, un nouveau système RPC pour navigateurs et serveurs web

• Cap'n Web est un nouveau protocole RPC implémenté en TypeScript, optimisé pour l’environnement web et capable de fonctionner sur plusieurs runtimes JavaScript
• Il fournit une sérialisation basée sur JSON et un format de données lisible par un humain, sans schéma ni boilerplate fastidieux
• Grâce à un modèle fondé sur les object-capabilities, il permet les appels bidirectionnels, le passage de références de fonctions et d’objets, le promise pipelining et l’implémentation de patterns de sécurité
• Il prend en charge divers environnements réseau comme WebSocket, HTTP, postMessage, tout en restant un open source léger de moins de 10 kB
• En plus de résoudre le problème de waterfall similaire à GraphQL, il permet une modélisation RPC naturelle, proche des API JavaScript classiques

---

Qu’est-ce que Cap'n Web ?

• Cap'n Web est un système open source de protocole RPC basé sur TypeScript développé par Cloudflare
• Il s’inspire de Cap'n Proto, mais fonctionne sans définition de schéma séparée et adopte une sérialisation conviviale pour les humains basée sur JSON
• Il est intégré à TypeScript, ce qui améliore l’expérience développeur avec l’autocomplétion et la vérification de types, tandis que la validation de types à l’exécution peut être gérée séparément (type guards, etc.)
• Il prend en charge des protocoles réseau comme HTTP, WebSocket et postMessage et fonctionne dans les principaux navigateurs, sur Cloudflare Workers, Node.js, etc.
• Sa structure légère sans dépendances permet une taille inférieure à 10 kB une fois minifié + gzip

Le modèle object-capability (OCap) de Cap'n Web

• Il adopte un modèle fondé sur les object-capabilities, qui permet une expression plus riche que les systèmes RPC traditionnels
  • Appels bidirectionnels : le client et le serveur peuvent appeler les fonctions l’un de l’autre
  • Passage de références de fonctions et d’objets : si une fonction ou un objet est transmis via RPC, l’autre partie reçoit un stub qui exécute l’appel à l’emplacement d’origine
  • Promise Pipelining : lorsqu’on enchaîne plusieurs RPC, le traitement se fait en un seul aller-retour réseau
  • Patterns de sécurité : il devient naturel d’implémenter des contrôles de sécurité comme l’autorisation et la gestion de session

Utilisation de base

• Exemple côté client

  import { newWebSocketRpcSession } from "capnweb"  
  let api = newWebSocketRpcSession("wss://example.com/api")  
  let result = await api.hello("World")  
  console.log(result)  
  

• Exemple côté serveur (basé sur Cloudflare Worker)

  import { RpcTarget, newWorkersRpcResponse } from "capnweb"  
  class MyApiServer extends RpcTarget {  
    hello(name) {  
      return `Hello, ${name}!`  
    }  
  }  
  export default {  
    fetch(request, env, ctx) {  
      let url = new URL(request.url)  
      if (url.pathname === "/api") {  
        return newWorkersRpcResponse(request, new MyApiServer())  
      }  
      return new Response("Not found", {status: 404})  
    }  
  }  
  

• Il est facile d’ajouter des méthodes à l’API, de transmettre une fonction de callback du client et de définir puis appliquer des interfaces TypeScript

Qu’est-ce que le RPC, et quelles sont les spécificités de Cap'n Web ?

• Le RPC (Remote Procedure Call) est un concept qui permet à deux programmes sur un réseau de communiquer comme s’il s’agissait d’appels de fonctions
• Contrairement aux protocoles HTTP/REST traditionnels, le RPC repose sur l’abstraction de l’appel de fonction, ce qui permet d’écrire du code aligné sur la façon de penser des développeurs
• Cap'n Web s’accorde bien avec les flux modernes de JavaScript, notamment grâce à la prise en charge de async/await, Promise et Exception
• Contrairement aux controverses historiques autour du RPC (appels synchrones, erreurs réseau), les environnements JS modernes permettent aujourd’hui une utilisation plus sûre et plus efficace

Cas d’usage de Cap'n Web

• Il est utile dans tout environnement nécessitant une communication réseau entre deux applications JavaScript
  • appels client-serveur, communication entre microservices, etc.
  • il convient particulièrement aux applications web de collaboration en temps réel et aux interactions franchissant des frontières de sécurité complexes
• Encore au stade expérimental, il sera particulièrement utile aux développeurs ouverts à l’adoption de technologies récentes

Différentes fonctionnalités

Mode batch HTTP

• Lorsqu’une connexion persistante n’est pas nécessaire, le mode batch HTTP permet de regrouper plusieurs appels RPC et de les traiter en une seule fois

  import { newHttpBatchRpcSession } from "capnweb"  
  let batch = newHttpBatchRpcSession("https://example.com/api";)  
  let result = await batch.hello("World")  
  console.log(result)  
  

• Plusieurs appels peuvent être exécutés simultanément dans un même batch, avec réception des résultats en parallèle

  let promise1 = batch.hello("Alice")  
  let promise2 = batch.hello("Bob")  
  let [result1, result2] = await Promise.all([promise1, promise2])  
  

Promise Pipelining (appels chaînés)

• Il prend en charge l’utilisation immédiate du résultat comme argument de l’appel suivant, sans attendre le résultat de l’appel précédent

• Exemple : transmettre directement la Promise renvoyée par getMyName() à hello() pour tout traiter en un seul aller-retour réseau

  let namePromise = batch.getMyName()  
  let result = await batch.hello(namePromise)  
  

• Dans Cap'n Web, les Promise fonctionnent comme des objets proxy, ce qui permet d’enchaîner des appels supplémentaires sans délai

  let sessionPromise = batch.authenticate(apiKey)  
  let name = await sessionPromise.whoami()  
  

Sécurité : authentification et object-capabilities

• Via la méthode authenticate, un objet de capacité (session) est attribué en cas de succès, permettant ensuite d’appeler des fonctionnalités sans étape d’authentification supplémentaire
• Contrairement aux RPC classiques, il est impossible de falsifier l’objet de session, et l’accès aux méthodes nécessitant des privilèges est impossible sans authentification
• Cela permet de surmonter naturellement les limites structurelles de WebSocket tout en garantissant la cohérence de la logique d’authentification
• Lorsqu’une interface API est déclarée en TypeScript, elle peut être appliquée automatiquement entre client et serveur, avec autocomplétion et sûreté de type

Comparaison avec GraphQL et différenciation de Cap'n Web

• GraphQL atténue le problème de waterfall de REST, mais nécessite l’introduction d’un nouveau langage, d’un schéma et d’une toolchain

• Cap'n Web résout le problème de waterfall avec du simple code JavaScript, et

  • grâce au promise pipelining et aux références d’objets, il permet de modéliser naturellement des appels imbriqués ou une logique transactionnelle complexe

  let user = api.createUser({ name: "Alice" })  
  let friendRequest = await user.sendFriendRequest("Bob")  
  

• Il peut être utilisé comme une API JavaScript classique, sans la complexité ni le coût d’apprentissage et de gestion de GraphQL

Opérations sur les tableaux (array.map, etc.) et optimisation

• Dans Cap'n Web, il est possible d’exécuter des opérations map sur chaque élément d’un tableau sans aller-retour réseau supplémentaire

• La fonction callback de map est exécutée une fois côté client pour enregistrer l’opération (record-replay), puis transmise au serveur pour traitement groupé

  let friendsWithPhotos = friendsPromise.map(friend => {  
    return {friend, photo: api.getUserPhoto(friend.id)}  
  })  
  let results = await friendsWithPhotos  
  

• Grâce à un DSL spécialisé et limité, cela s’exprime comme une fonction JavaScript tout en utilisant en réalité le protocole Cap'n Web pour optimiser plusieurs appels

Structure interne du protocole et flux de communication

• Transmission de données structurées via JSON + prétraitement spécial, avec prise en charge de types particuliers comme les tableaux et les dates
• En tant que protocole symétrique, il permet une communication bidirectionnelle sans distinction client/serveur
• Chaque partie (par exemple Alice et Bob) gère des tables d’export/import et distingue les références d’objets et de fonctions via des identifiants
• Grâce aux messages push/pull et à l’attribution d’identifiants de Promise, plusieurs appels peuvent être reflétés dans un seul aller-retour

État actuel et cas d’adoption

• Cap'n Web est encore un open source expérimental, déjà utilisé dans des services réels comme les remote bindings de Cloudflare Wrangler
• D’autres billets de blog et diverses expérimentations frontend sont prévus
• Il est publié sous licence MIT et peut être adopté librement par tous
• Accéder au dépôt GitHub