No REST para Cap'n Web

Hola. Gracias por venir. Mi nombre es Kenton Varda. Soy el desarrollador principal de la plataforma de desarrollo de Cloudflare Workers, un proyecto que comencé hace unos nueve años. También soy el creador de CapnProto y ahora CapnWeb. Hoy, me gustaría convencerte de que si todos usaran CapnWeb en lugar de REST para APIs web, el mundo sería un lugar mejor, tanto para los humanos como para los agentes de IA.

Entonces, ¿qué es CapnWeb? CapnWeb es un protocolo RPC. RPC significa llamada a procedimiento remoto. Y la idea es que estás expresando tus comunicaciones entre un cliente y un servidor como llamadas a funciones en lugar de como solicitudes y respuestas. Y así se siente como si las comunicaciones fueran como llamar a una biblioteca en lugar de llamar a un servicio de red.

Entonces, ¿cómo se ve eso con CapnWeb? Este es un hola mundo muy básico, cliente y servidor CapnWeb. Así que en el lado del servidor, declaramos esta clase, que define nuestra interfaz RPC. Así que todos los métodos de esta clase van a estar expuestos al cliente. Así que tenemos un método greet aquí. Devuelve hola nombre. Y luego aquí abajo está básicamente el código estándar para configurar la aceptación de estas solicitudes RPC en CloudFlare Workers.

código estándar para configurar la aceptación de estas solicitudes RPC en CloudFlare Workers. Así que CapnWeb no es exclusivo de CloudFlare Workers. Soporta todos los entornos de ejecución de JavaScript. Pero estoy usando, bueno, el código es un poco diferente para cada entorno de ejecución.

Y estoy usando CloudFlare Workers aquí. Así que todo lo que hay aquí es un manejador HTTP estándar de CloudFlare Workers. Y simplemente está pidiendo a la biblioteca CapnWeb que construya una respuesta a partir de la solicitud y exponga una instancia de esta clase greeter al cliente. El lado del cliente es bastante simple también.

El cliente simplemente llama a esta función de CapnWeb, establece una nueva sesión RPC sobre WebSocket a esta URL. CapnWeb también soporta un transporte HTTP regular y algunas otras opciones. Pero realmente funciona mejor sobre WebSocket por razones que verás en un momento.

Un stub es una referencia a un objeto remoto. Es un sustituto. Llamas a métodos en el stub y eso hace que esos métodos se llamen en el objeto remoto. Así que aquí llamamos a greeter.greet.

Eso va a enviar un mensaje al servidor, llamar a este método, obtener la respuesta de vuelta. Ahora, una cosa interesante sobre estos stubs, sin embargo, es que el stub en realidad no sabe qué métodos existen en el servidor. Ves que en realidad no hay oportunidad de averiguarlo aquí porque no hemos esperado nada. Así que no hay oportunidad de preguntar al servidor, oye, ¿cuál es tu interfaz?

Y no queremos que lo haga porque si lo hiciera, eso sería un viaje adicional y sería más lento. Así que en su lugar, la forma en que funciona un stub es que es un objeto proxy de JavaScript y pretende que tiene todos los posibles nombres de métodos. Y así puedes llamar a cualquier nombre de método aleatorio aquí, e intentará llamar a eso en el servidor. Y solo cuando el mensaje llega al servidor detectará que ese método no existe.

cuanto a la comprobación de tipos de TypeScript, los métodos son conocidos porque en tiempo de escritura, importamos este tipo desde el servidor. Y esta es una importación solo de tipo, por lo que no crea una dependencia entre el código del cliente y el servidor. Pero importa este tipo, y luego lo pasamos a Cat and Web aquí. Y Cat and Web realmente hará que esta cosa tenga un tipo que hace que parezca que tiene todos los métodos correctos en él. Por supuesto, si prefieres no importar directamente desde tu código de servidor, podrías separar un archivo de interfaz de TypeScript por separado y hacer que ambos importen eso también. Todo funciona.

Así que antes de continuar con las características interesantes de Cat and Web, quiero establecer un caso de ejemplo. Así que digamos que estamos construyendo una API de chat o un servicio de chat como un Slack o un Discord. Y esta es una API REST básica para eso, para una versión simplificada de eso. Ahora, estoy expresando esto de manera informal porque, como verás en un momento, si intentara expresarlo formalmente, se vuelve demasiado complicado. Pero esto es muy simple, directo. Tenemos un endpoint para obtener una lista de todos los nombres de salas. Tenemos un endpoint para obtener mensajes, el historial de chat de una sala en particular, tomar algunos parámetros de consulta, devolver algunos mensajes. Tenemos un endpoint para publicar un nuevo mensaje en una sala en particular. Y todos estos requieren autorización, por lo que podría venir en forma de un encabezado de autorización o tal vez una cookie.

Y sí, tenemos estos tipos de TypeScript que he definido al margen, que son representaciones de lo que vamos a poner en los parámetros de consulta o en la salida JSON aquí. Ahora, digamos que queremos convertir esta API a Cat and Web, y lo vamos a hacer de una manera un tanto ingenua y directa. Vamos a convertir cada uno de estos endpoints en un método en nuestra API de chat. Así que listar salas, obtener historial, enviar. Y con HTTP, tenemos muchos lugares diferentes en la solicitud donde puedes poner las entradas, pero en Cat and Web, solo tienes uno. Son solo los parámetros del método. Así que tenemos que tomar todas las cosas que estaban en una solicitud HTTP y convertirlas en parámetros aquí. Así que el token termina siendo un parámetro para cada uno de estos métodos. No hay URL. Ponemos el nombre de la sala como un parámetro, etc. Y luego podemos reutilizar estos tipos de TypeScript que definimos antes. Así que ¿cómo termina luciendo el código? Así que a la izquierda, tenemos un código para llamar a nuestra API REST. Y como es una API HTTP, tienes que llamar a fetch, y tienes que hacer una especie de mucho de este código repetitivo alrededor de configurar solicitudes HTTP. Y se pone un poco feo.

este código repetitivo alrededor de configurar solicitudes HTTP. Y se pone un poco feo. Y en la práctica, nadie realmente escribe este código en bruto. Lo que terminan haciendo en su lugar es usar una biblioteca de cliente proporcionada por el autor de la API. Y entonces, lo que he hecho aquí es definir algunas funciones auxiliares que esencialmente serían esa biblioteca de cliente. Luego, una vez que tenemos esos auxiliares aquí abajo, podemos escribir algo de código y es sencillo llamar a estos métodos. En el lado de Cat and Web, verás que las cosas son mucho más simples. Iniciamos nuestra sesión y luego simplemente comenzamos a llamar cosas. Y notarás que este código aquí que llama a la API sobre Cat and Web se ve exactamente como este código aquí. Pero no tenemos una biblioteca de cliente excepto por Cat and Web en sí.

No tenemos nada específico para la API particular que estamos llamando. Y creo que eso es una mejora bastante grande. Ahora, veamos cómo especificas estas APIs formalmente. Así que cuando tienes una API REST, la forma estándar de facto de definir la API hoy en día es a través de esquemas de open API. Y se ven así. Es un montón de YAML. Esta es la especificación para esa simple API de chat que teníamos antes. Como puedes ver, se vuelve bastante larga, incluso para una API tan simple. Y no sé tú, pero cuando intento leer esto, como que no puedo leerlo porque empiezo a leer un par de cosas y simplemente me distraigo o me quedo dormido o algo así. Mientras tanto, en el lado de Cat and Web, Cat and Web se especifica simplemente con TypeScript. Así que esto es, ya sabes, simple, directo, fácil de leer.

Es el formato al que estás acostumbrado. Mucho mejor, en mi opinión. Pero podemos ir más allá. Esto fue solo una traducción ingenua, como dije antes. Pero hay más que podemos hacer aquí. Por ejemplo, no me gusta mucho que tengamos que pasar este token de autenticación a cada una de estas funciones. Sería bueno si pudiéramos eliminar eso. Resulta que podemos. Así que esto utiliza una característica de Cat and Web que casi ningún otro sistema RPC tiene, que es que puedes introducir nuevos objetos en tiempo de ejecución.

Y ahora esos no necesitan tomar tokens. Y la forma en que esto funciona, entonces este objeto de auth chat API que se devuelve es específico para la sesión RPC particular. No tiene una URL. No tiene un identificador global de ningún tipo. Existe dentro del contexto de esta conexión. Y cómo funciona eso es que es algo así como descriptores de archivo. Así que hay una tabla asociada con la conexión que asigna a cada objeto un número.

Así que la interfaz inicial chat API se asignará al número cero. Y luego, cuando se devuelve auth chat API, obtendrá el número uno. Pero esos números no se asignan hasta que los objetos se introducen realmente. Así que el cliente no tiene forma de hablar con el auth chat API hasta que haya llamado con éxito a authorize y haya tenido eso devuelto. Así que esto es realmente seguro.

Y es bastante agradable porque si autorizar este token requiere algún trabajo, como hacer algunas búsquedas, podemos hacer eso una vez. Y luego el cliente puede hacer varias llamadas a métodos en este objeto autorizado basado en esa única autorización en lugar de tener que hacerlo una y otra vez en cada solicitud. Así que no solo se ve mejor, también es más eficiente. A continuación, podemos ir un poco más allá. Y podemos separar las salas de chat. Así que aquí hemos movido estos dos métodos que operan en salas a un objeto separado llamado chat room API, que representa una sala de chat en particular.

Y luego tenemos un método get room que obtiene una sala en particular. Esto es genial porque si algunos usuarios solo tienen acceso a algunas salas, entonces podemos hacer esa verificación de si el usuario tiene permitido visitar esta sala en el momento en que se llama a get room, y no en cada solicitud a la sala. Así que una vez más, se ve mejor y funciona mejor.

Y hay más aquí para que obtengas la gestión del ciclo de vida de esto. Así que en el lado del servidor, cuando implementamos este chat room API, tiene un constructor y opcionalmente un disposer. Así que symbol dot dispose. Esta es la sintaxis estándar de la característica de gestión explícita de recursos de ECMAScript. Es una característica relativamente nueva en JavaScript de los últimos años, pero es estándar. Y este disposer que declaras se llamará cuando el cliente elimine su stub o cuando se pierda la conexión.

Así que en el lado del servidor, tienes la promesa de que esto será llamado. Y así, si hay una configuración costosa que tienes que hacer y no quieres repetirla en una API REST, normalmente tienes que configurar algo como almacenamiento en caché o algo y tienes que adivinar cuándo el cliente se ha ido porque, sabes, hay algún tiempo de espera. Y eso se vuelve bastante complicado. Aquí sabemos exactamente cuándo el cliente ha terminado porque llaman al disposer. Así que todo esto suena genial, pero podrías tener una objeción en este punto. Podrías decir, oye, ¿no es esto más lento? Así que antes, si todo lo que quería hacer era una solicitud para obtener el registro de chat de una sala en particular, eso es solo una solicitud. Envío la solicitud, obtengo una respuesta. Es un viaje de ida y vuelta al servidor.

Pero ahora en esta API multinivel que tenemos con Cat and Web, parece que primero tengo que llamar a authorize y luego tengo que esperar la respuesta. Y luego tengo que llamar a get room y tengo que esperar la respuesta. Y luego llamo a get history y espero la respuesta. Así que son tres viajes de ida y vuelta. ¿No acabamos de hacer todo mucho más lento de esta manera? ¿No es eso bastante malo? Bueno, Cat and Web tiene una solución para esto, que básicamente puedes simplemente eliminar esos dos primeros awaits porque un método RPC de Cat and Web devuelve una promesa que no es una promesa normal de JavaScript. En realidad, es un objeto proxy en sí mismo. Y se puede esperar, pero también puedes simplemente comenzar a llamar métodos sobre él. Y así, si llamas a este método get room en la promesa, entonces el cliente va a decirle al servidor, oye, cuando authorize termine, espera que va a devolver un stub y luego llama a esta siguiente cosa sobre él inmediatamente. Y así el cliente puede encolar toda esta cadena de llamadas a métodos, todo en una rápida serie de mensajes, enviar esos al servidor, y en un viaje de ida y vuelta, obtiene los resultados. Esta es una característica llamada promise pipelining, es otra característica que casi ningún otro sistema RPC tiene. Es bastante único para Cat and Web y algunos sistemas de investigación. Y Cat and Proto también, por supuesto.

Una característica más que quiero mostrarte, así que Cat and Web es en realidad un protocolo simétrico. He estado hablando de un cliente y un servidor, pero desde el punto de vista de Cat and Web, no hay cliente y servidor. Solo hay dos pares hablando entre sí. Y cualquiera de los lados puede exponer interfaces al otro. Y cualquiera de los lados puede realmente enviar nuevos objetos, nuevos stubs al otro lado en los parámetros de las llamadas que están haciendo. Y otra cosa que no mencioné antes, un stub RPC no está limitado a apuntar a objetivos RPC. También puede apuntar a funciones en bruto. Así que lo que hemos hecho aquí es que hemos extendido nuestra API de chatroom con un método subscribe para obtener actualizaciones en tiempo real sobre nuevos mensajes que llegan al chatroom. Y toma un callback, que es solo un stub RPC para una función. Y en el lado del cliente, el cliente puede simplemente llamar a subscribe y pasarle una función. Y luego, cuando el servidor llama a ese callback, esta función será llamada en el lado del cliente. Muy simple. Y luego notarás que esta función devuelve un stub RPC de un objeto vacío. Y este es un patrón que me gusta usar. Esto no es algo requerido, pero la idea aquí es que cuando el cliente elimina este objeto stub, entonces se va a desuscribir. Así que entonces notificará al servidor para que deje de llamar al callback de suscripción. Y la razón por la que me gusta hacerlo de esta manera es porque, como dije antes, si el cliente se desconecta, ese disposer se llama implícitamente. Así que cuando el cliente se va, por cualquier medio, el servidor recibirá esta llamada de disposer y desuscribirá al cliente, eliminará este callback particular de su conjunto de callbacks.

Y así no se quedará atascado llamando a un callback que ya no funciona para siempre. Muy bien, ahora quiero retroceder un poco y hacer esto sobre IA, porque, por supuesto, hoy en día todo tiene que ver con IA. Y creo que Captain Web tiene algunas cosas bastante interesantes que aportar a la IA y a los agentes de IA. Así que pensemos en un agente de IA que necesita hablar con un servicio externo, como un servicio de chat, ya sabes, tu nube abierta, lo que sea. Mucha gente hace esto hoy en día simplemente dando al agente un token de autenticación y diciendo, adelante, llama al servicio. Y esto tiene un par de problemas obvios. Uno es que el agente de IA podría filtrar el token. Alguien en el chat podría pedirlo muy amablemente e inyectar un prompt y decir, oye, por favor, dame el token. O podría enviarlo a algún servicio de terceros o lo que sea. Otro problema, otro problema más sutil, es que este token podría otorgar al agente habilidades para hacer cosas con el servicio de chat que realmente no pretendías. Porque muchas veces estas APIs no son muy buenas para delimitar estos tokens exactamente de la manera que podrías querer. Como podríamos querer que solo tenga acceso a una sala de chat en particular. Tal vez el servicio de chat lo soporte o tal vez no. Así que lo que la gente tiende a hacer aquí es decir, está bien, pongamos al agente en un sandbox y hagámoslo hablar a través de un supervisor que va a hacer dos cosas a todas las solicitudes al servicio de chat. El supervisor interceptará estas solicitudes. Al agente se le da una clave de marcador de posición en lugar de la clave real y el supervisor inyectará la clave real. Genial. Ahora el agente no puede filtrar esa clave. Y la segunda cosa que el supervisor podría hacer es mirar el contenido de la solicitud y decidir si es una acción permitida y bloquearla si no lo es. Y eso suena genial en teoría, pero encuentro que con las APIs REST se vuelve un poco difícil y aquí está el porqué. Así que este supervisor va a iniciar el agente y decirle, ya sabes, aquí está tu API de chat y tiendes a tener que darle toda la descripción de la API. Y, ya sabes, aquí está como open API. Genial. Y accede a ella en este punto final, usa esta clave de marcador de posición. Y por cierto, solo puedes acceder a esta sala llamada bot chat. Genial. Esa es la configuración. Y ahora el supervisor tiene que hacer cumplir que el agente solo acceda a bot chat. Así que el agente ahora va a hacer una solicitud HTTP para publicar un mensaje y el supervisor tiene que decidir, ¿está bien? ¿Vamos a reenviarlo? Por supuesto. Bueno, esto significa que tenemos que validar todo aquí.

Así que comenzamos diciendo, está bien, sí, usa su clave de marcador de posición. Pondremos la clave real allí. Tenemos que asegurarnos de que estamos yendo al nombre de host correcto porque de lo contrario estamos filtrando esa clave a algún otro host. Tenemos que asegurarnos de que el mensaje vaya a la sala de chat correcta, lo cual hacemos verificando que la ruta tenga el prefijo correcto. Genial. Pero también hay todas estas otras cosas en la solicitud HTTP que ahora tenemos que averiguar, como el encabezado de fecha. ¿Tenemos que validar esto? ¿Es malo si el agente puede enviar una fecha no válida? ¿A alguien en toda la historia de HTTP le ha importado el encabezado de fecha? No realmente. Así que probablemente no nos importe eso. Probablemente necesitemos validar que el tipo de contenido sea correcto porque probablemente necesitemos validar los contenidos y poder analizarlos. Pero esto se puede expresar de diferentes maneras. Como puede tener un conjunto de caracteres o no tenerlo. Así que ahora necesitamos un analizador de tipo MIME y necesitamos validar todo eso. Eso se vuelve raro. Probablemente necesitemos validar la longitud del contenido. Tenemos este encabezado de aceptación. ¿Necesitamos validar eso? ¿Nos importa cuál es el tipo de contenido? El agente recibe de vuelta probablemente no, pero no lo sé. Esto obviamente necesita ser validado. Y luego aquí el agente ha enviado este otro encabezado que es este encabezado misterioso que podría significar cualquier cosa. Sabes, aparentemente tiene algo que ver con el aprendizaje por refuerzo o algo así, pero no sabemos qué es esto. Es simplemente opaco. Así que tenemos que preguntar qué hacemos con esto. ¿Eliminamos este encabezado? ¿Lo dejamos porque creemos que es inofensivo? ¿Rechazamos toda la solicitud hasta que el agente, por favor, por favor, elimine eso la próxima vez? Se vuelve realmente raro.

Bien. Así que ahora digamos que estamos usando Kaban web en su lugar. Así que la configuración ahora es simplemente decirle al agente, la interfaz de TypeScript, que es mucho más pequeña y mucho más fácil para que los agentes entiendan porque los agentes, ya sabes, los LLMs tienen muchos datos de entrenamiento de TypeScript y no tanto de open API y menos tokens les das, más inteligentes tienden a ser. Pero también podemos hacer algo realmente interesante aquí, que es que queríamos que este agente solo tuviera acceso a una sala de chat. Y nuestra API tiene este objeto de API de sala de chat. Y así que podemos simplemente darle un stub que ya es específico para una sala de chat. No tenemos que decirle sobre el nivel superior, la API de autorización o la API de lista de salas, porque no puede usar esas de todos modos. Así que simplemente las dejamos fuera. Le damos un stub.

Así que cuando tienes un stub de CapnWeb, puedes pasarlo a través de otra conexión de CapnWeb. Y solo pasa ese stub y no la interfaz más amplia de la que proviene. Así que ahora le damos al agente solo ese stub y puede llamar a lo que quiera en eso. Y no tenemos nada que validar porque está restringido a una sola sala. Genial.

Todo esto se volvió mucho más simple. Lo que acabo de mostrarles es un ejemplo de una técnica llamada seguridad basada en capacidades. Casi todas las sandbox exitosas jamás creadas utilizan seguridad basada en capacidades hasta cierto punto, porque hace que sea mucho más fácil razonar sobre lo que la aplicación en la sandbox puede y no puede hacer.

Algo que no mucha gente sabe es que el "cap" en CapnWeb y CapnProto no significa "capitán". En realidad, es una abreviatura de "capacidades" y porque estos protocolos fueron diseñados para ser protocolos basados en capacidades y diseñados específicamente para sandboxing. Y funcionan muy bien para eso. Así que en estos próximos días de agentes de IA, todos van a necesitar ser ingenieros de sandbox y tal vez sea una buena idea aprender sobre estas cosas y probarlo. Eso es todo lo que tengo. Gracias por venir.