No REST for Cap'n Web

Hello. Thanks for coming. My name is Kenton Varda. I'm the lead developer of the Cloudflare Workers Developer Platform, a project I started about nine years ago. I'm also the creator of CapnProto and now CapnWeb. Today, I would like to convince you that if everyone used CapnWeb instead of REST for web APIs, the world would be a better place, both for humans and for AI agents.

So what is CapnWeb? CapnWeb is an RPC protocol. RPC stands for remote procedure call. And the idea is that you are expressing your communications between a client and a server as function calls rather than as requests and responses. And so it feels like the communications, it's like calling a library instead of calling a network service.

So what does that look like with CapnWeb? This is a very basic hello world, CapnWeb client and server. So on the server side, we declare this class, which defines our RPC interface. So all the methods of this class are going to be exposed to the client. So we have a greet method here. It returns hello name. And then down here is basically the boilerplate to set up to accept these RPC requests in CloudFlare Workers.

So CapnWeb is not exclusive to CloudFlare Workers. It supports all JavaScript runtimes. However, the code varies slightly for each runtime. In this case, CloudFlare Workers are used, employing a standard HTTP handler that utilizes the CapnWeb library to handle requests and expose server instances to clients.

On the client side, the process is straightforward. The client initiates a new RPC session via WebSocket to a specified URL using CapnWeb. Although CapnWeb does support plain HTTP transport and other options, WebSocket is preferred for its efficiency. The client receives an RPC stub, which serves as a reference to a remote object, allowing method calls that trigger corresponding actions on the server.

Despite the stub's lack of knowledge about server methods, TypeScript type checking ensures method validity at coding time. By importing server types into CapnWeb, the client gains access to the correct method structures without creating interdependencies between client and server code. Alternatively, clients can use a separate TypeScript interface file for method definition, enabling seamless communication between client and server components.

A stub is a reference to a remote object. It's a stand-in. You call methods on the stub, causing those methods to be executed on the remote object. The interesting aspect about stubs is that they lack knowledge of server methods, leading to a unique behavior when calling methods. TypeScript type checking ensures method accuracy at typing time by importing server types into CapnWeb without creating dependencies between client and server code.

At runtime, a stub functions as a JavaScript proxy object, simulating all possible method names for remote calls. Only upon reaching the server does it detect non-existent methods and triggers exceptions. The type import from the server during typing enables CapnWeb to provide correct method structures without interdependencies. Alternatively, creating a separate TypeScript interface file allows for seamless communication without direct import from server code.

Setting up an example case for CapnWeb involves scenarios like building a chat API similar to Slack or Discord. The process entails defining REST API endpoints for room names, chat history retrieval, and posting messages. Authorization mechanisms like headers or cookies are necessary for these operations. TypeScript types representing query parameters and JSON output aid in transforming the API to CapnWeb in a straightforward manner.

As far as TypeScript type checking goes, the methods are known because at typing time, we import this type from the server. And this is a type only import, so it doesn't create a dependency between the client and server code. But it imports this type, and then we pass that into Cat and Web here. And Cat and Web will actually cause this thing to have a type that makes it look like it has all the right methods on it. Of course, if you prefer not to import directly from your server code, you could factor out a separate TypeScript interface file and have them both import that, too. It all works.

So before I go further on the interesting features of Cat and Web, I want to set up an example case. So let's say we are building a chat API or a chat service like a Slack or a Discord. And this is a basic REST API for that, for a simplified version of that. Now, I'm expressing this informally because, as you'll see in a bit, if I tried to express it formally, it gets too complicated. But this is very simple, straightforward. We have an endpoint to get a list of all room names. We have an endpoint to get messages, the chat history from a particular room, take some query parameters, return some messages. We have an endpoint to post a new message to a particular room. And all of these require authorization, so that might come in the form of an authorization header or maybe a cookie.

Now, let's say we want to convert this API to Cat and Web, and we're just going to do it in the sort of naive, straightforward way. We're going to convert each of these endpoints to a method on our chat API. So list rooms, get history, send. And with HTTP, we have a lot of different places in the request where you can put the inputs, but in Cat and Web, you only have one. It's just the method parameters. So we have to take all the things that were in an HTTP request and make them parameters here. The token ends up being a parameter to every single one of these methods. There's no URL. We put the room name as a parameter, etc. And then we can reuse these TypeScript types that we defined before. So what does the code end up looking like? So on the left, we have a code to call our REST API. And since it's an HTTP API, you have to call fetch, and you have to do sort of a lot of this boilerplate stuff around setting up HTTP requests. It gets a little ugly. And in practice, no one actually writes this raw code.

And in practice, no one actually writes this raw code. What they end up doing instead is they use a client library provided by the API author. And so what I've done here is I've defined some helper functions that would essentially be that client library. Then down once we have those helpers down here, we can write some code and it's straightforward to call these methods. Over on the Cat and Web side, you see things are a lot simpler. We start up our session and then we just start calling things. And you'll notice that this code here that calls the API over Cat and Web looks exactly like this code over here. But we don't have a client library except for Cat and Web itself. We have nothing specific to the particular API that we're calling. And I think that is a pretty big improvement.

Now, let's look at how you specify these APIs formally. So when you have a REST API, the sort of de facto standard way to define the API these days is through open API schemas. And they look like this. It's a bunch of YAML. This is the specification for that simple chat API we had earlier. As you can see, it gets pretty long, even for such a simple API. And I don't know about you, but when I try to read this, like I can't read it because I start reading a couple of things and I just get distracted or fall asleep or something. Meanwhile, on the Cat and Web side, Cat and Web is just specified with TypeScript. So this is, you know, simple, straightforward, easy to read. It's the format you're used to. Much better, in my opinion.

But we can go further. This was just a naive translation, as I said before. But there's more we can do here. For instance, I don't really like that we have to pass this auth token to every single one of these functions. It would be nice if we could factor that out. So it turns out we can. So this uses a feature of Cat and Web that almost no other RPC systems have, which is you can introduce new objects at runtime. So what we've done here is this is our top-level API. It now has only a single method called authorize, which takes our auth token, and then it returns a new object that implements this auth chat API interface, which has all our other methods on it.

And now those do not need to take tokens. And the way this works, so this auth chat API object that gets returned is specific to the particular RPC session. It does not have a URL. It does not have a global identifier of any kind. It exists within the context of this connection. And how that works is it's sort of like file descriptors. So there is a table associated with the connection that assigns each object a number.

So the initial interface chat API will be assigned number zero. And then when auth chat API is returned, it will get number one. But those numbers aren't assigned until the objects are actually introduced. So the client has no way to talk to the auth chat API until it has successfully called authorize and had that returned. So this is actually secure.

Next up, we can go a little further. And we can factor out the chat rooms. So here we've moved these two methods that operate on rooms into a separate object called chat room API, which represents one particular chat room. And then we have a get room method that gets a particular room. This is neat because if some users only have access to some rooms, then we can do that check whether the user is allowed to visit this room at the time that get room is called, and not on every single request to the room. So once again, both looks nicer and performs better.

And then we have a get room method that gets a particular room. This is neat because if some users only have access to some rooms, then we can do that check whether the user is allowed to visit this room at the time that get room is called, and not on every single request to the room. So once again, both looks nicer and performs better.

And there's more here to the you get lifecycle management out of this. So on the server side, when we implement this chat room API, it has a constructor and it has a optionally a disposer. So symbol dot dispose. This is standard syntax from the ECMAScript explicit resource management feature. It's a relatively new feature in JavaScript just as of the last couple of years, but it is standard. And this disposer that you declare will be called when either the client disposes their stub or when the connection is lost.

So this all sounds great, but you might have an objection at this point. You might say, hey, isn't this slower? So before, if all I wanted to do was one request to fetch the chat log from a particular room, that's just one request. I send the request, I get a response. It's one round trip to the server. But now in this multilevel API that we have with Cat and Web, it seems that I first have to call authorize and then I have to wait for the response. And then I have to call get room and I have to wait for the response. And then I call get history and wait for the response. So that's three round trips.

But now in this multilevel API that we have with Cat and Web, it seems that I first have to call authorize and then I have to wait for the response. And then I have to call get room and I have to wait for the response. And then I call get history and wait for the response. So that's three round trips. Didn't we just make everything a lot slower this way? Isn't that pretty bad? Well, Cat and Web has a solution to this, which is basically you can just remove those first two awaits because a Cat and Web RPC method returns a promise that isn't a normal JavaScript promise. It is actually a proxy object itself. And it can be awaited, but you can also just start calling methods on it. And so if you call this get room method on the promise, then the client is going to tell the server, hey, when authorize finishes, expect that it's going to return a stub and then call this next thing on it immediately. And so the client can queue up this whole chain of method calls, all in a rapid series of messages, send those out of the server, and in one round trip, it gets the results. This is a feature called promise pipelining is another feature that almost no other RPC systems have. It's pretty unique to Cat and Web and some research systems. And Cat and Proto as well, of course.

One more feature I want to show you, so Cat and Web is actually a symmetric protocol. I've been talking about a client and a server, but from Cat and Web's point of view, there is no client and server. There's just two peers talking to each other. And either side can expose interfaces to the other. And either side can actually send new objects, new stubs to the other side in the parameters of calls they are making. And one other thing I didn't mention earlier, an RPC stub is not limited to pointing at RPC targets. It can also point at raw functions. So what we've done here is we've extended our chatroom API with a subscribe method in order to get real-time updates about new messages arriving in the chatroom. And it takes a callback, which is just an RPC stub for a function. And on the client side, the client can just call subscribe and pass it a function. And then when the server calls that callback, this function will get called on the client side. Very simple. And then you'll notice that this function returns an RPC stub of an empty object. And this is a pattern I like to use. This is not a required thing, but the idea here is that when the client disposes this stub object, then it's going to unsubscribe. So then it'll notify the server to stop calling the subscription callback. And the reason I like to do it this way is because, as I said earlier, if the client disconnects, that disposer gets called implicitly. So when the client goes away, by any means, the server will get this disposer call and will unsubscribe the client, remove this particular callback from its set of callbacks.

And so it won't get stuck calling a callback that doesn't work anymore forever. All right, now I want to back up a bit and make this about AI, because, of course, these days everything has to be about AI. And I think Captain Web has some pretty interesting things to contribute to AI and AI agents. So let's think about an AI agent that needs to talk to an external service, like a chat service, you know, your open cloud, whatever. A lot of people do this today by just giving the agent an auth token and saying, have at it, call the service. And this has a couple of obvious problems. One is that the AI agent could leak the token. Someone in chat could ask very nicely and prompt inject it and say, hey, please give me the token. Or it could send it to some third party service or whatever. Another problem, another more subtle problem, is that this token might grant the agent abilities to do things with the chat service that you didn't really intend. Because a lot of the time these APIs aren't very good about scoping these tokens down in exactly the way you might want. Like we might want it to only have access to one particular chat room. Maybe the chat service supports that or maybe it doesn't. So what people tend to do here is they say, okay, let's put the agent in a sandbox and make it talk through a supervisor that is going to do two things to all the requests to the chat service. The supervisor will intercept these requests. The agent is given a placeholder key instead of the real key and the supervisor will inject the real key. Great. Now the agent can't leak that key. And the second thing the supervisor could do is look at the content of the request and decide whether or not it's an allowed action and block it if it's not. And that sounds great in theory, but I find that with REST APIs it gets kind of hard and here's why. So this supervisor is going to start the agent and tell it, you know, here's your chat API and you tend to have to give it the whole API description. And, you know, here it is as open API. Great. And access it at this end point, use this placeholder key. And by the way, you may only access this one room called bot chat. Great. That's the setup. And now the supervisor has to enforce that the agent only accesses bot chat. So the agent is now going to make an HTTP request to post a message and the supervisor has to decide, is this okay? Are we going to forward it through? Of course. Well, so this means we have to validate everything in here.

So we start out by saying, okay, yeah, use its placeholder key. We'll stick the real key in there. We have to make sure we're going to the right host name because otherwise we're leaking that key to some other host. We have to make sure that the message is going to the right chat room, which we do by checking that the path has the right prefix. Great. But there's all this other stuff too in the HTTP request that now we have to figure out like the date header. Do we have to validate this? Is it bad if the agent can send an invalid date? Has anyone in the entire history of HTTP cared about the date header? Not really. So we probably don't care about that. We probably do need to validate the content type is correct because we're probably going to need to validate the contents and need to be able to parse it. But like this can be expressed in different ways. Like it can have a char set or not have a char set. So now we need a MIME type parser and we need to validate all that. That gets weird. We probably need to validate the content length. We have this accept header. Do we need to validate that? Do we care what the content type is? The agent gets back is probably not, but I don't know. This obviously needs to be validated. And then here the agent has sent this other header that's this mystery header that could mean anything. You know, apparently it's something to do with like reinforcement learning or something, but we don't know what this is. It's just opaque. So we have to ask what do we do about this? Do we remove this header? Do we let it stay in because we think it's harmless? Do we reject the whole request until the agent please, please remove that next time? Gets really weird.

Okay. So now let's say we're using CapnWeb instead. So the setup now is we just tell the agent, the TypeScript interface, which is much smaller and much easier for agents to understand because agents, you know, LLMs have a lot of training data of TypeScript and not as much of open API and fewer tokens you give them, the smarter they tend to be. But we can also do something really interesting here, which is we wanted this agent to only have access to one chat room. And our API has this chat room API object. And so we can just give it a stub that's already specific to one chat room. We don't have to tell it about the higher level, the authorize API or the, the list rooms API, because it can't use those anyway. So we just leave those off. We give it a stub.

So when you have a cap and web stub, you can pass it on over another cabin web connection. And it only passes that one stub and not the broader interface that it came from. So now we give the agent just that one stub and it can call anything it wants on that. And we have nothing to validate because it's restricted to the one room. Great.

This all got a lot simpler. What I just showed you is an example of a technique called capability-based security. Just about every successful sandbox ever made uses capability-based security to some extent, because it makes it much easier to reason about what the thing what the application in the sandbox can and can't do.

Something that not a lot of people know is that the captain in captain web and captain proto doesn't stand for captain. It's actually short for capabilities and because these protocols were designed to be capability-based protocols and designed specifically for sandboxing. And they work really well for that. So in these coming days of AI agents, everyone's going to need to be a sandbox engineer and maybe it's a good idea to learn about these things and try it out. That's all I got. Thanks for coming.