Low-Level HTTP Request Handler

Actors can handle HTTP requests through the onRequest handler.

For most use cases, actions provide high-level API powered by HTTP that's easier to work with than low-level HTTP. However, low-level handlers are required when implementing custom use cases or integrating external libraries that need direct access to the underlying HTTP Request/Response objects or WebSocket connections.

Handling HTTP Requests

The onRequest handler processes HTTP requests sent to your actor. It receives the actor context and a standard Request object and returns a Response object.

import { actor } from "rivetkit";

export const counterActor = actor({
    state: {
        count: 0,
    },
    // WinterTC compliant - accepts standard Request and returns standard Response
    onRequest: (c, request) {
        const url = new URL(request.url);

        if (request.method === "GET" && url.pathname === "/count") {
            return Response.json({ count: c.state.count });
        }

        if (request.method === "POST" && url.pathname === "/increment") {
            c.state.count++;
            return Response.json({ count: c.state.count });
        }

        return new Response("Not Found", { status: 404 });
    },
});

See also the raw fetch handler example.

Sending Requests To Actors

Via RivetKit Client

Use the .fetch() method on an actor handle to send HTTP requests to the actor's onRequest handler. This can be executed from either your frontend or backend.

import { createClient } from "rivetkit/client";

const client = createClient();

const actor = client.counter.getOrCreate("my-counter");

// .fetch() is WinterTC compliant, it accepts standard Request and returns standard Response
const response = await actor.fetch("/increment", { method: "POST" });
const data = await response.json();
console.log(data); // { count: 1 }

Via HTTP API

This handler can be accessed with raw HTTP using https://api.rivet.dev/gateway/{actorId}/request/{...path}.

For example, to call POST /increment on the counter actor above:

const response = await fetch(
  `https://api.rivet.dev/gateway/${actorId}/request/increment`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
    },
  }
);
const data = await response.json();
console.log(data); // { count: 1 }

The request is routed to the actor's onRequest handler where:

• request.method is "POST"
• request.url ends with /increment (the path after /request/)
• Headers, body, and other request properties are passed through unchanged

See the HTTP API reference for more information on HTTP routing and authentication.

Via Proxying Requests

You can proxy HTTP requests from your own server to actor handlers using the RivetKit client. This is useful when you need to add custom authentication, rate limiting, or request transformation before forwarding to actors.

import { Hono } from "hono";
import { createClient } from "rivetkit/client";
import { serve } from "@hono/node-server";

const client = createClient();

const app = new Hono();

// Proxy requests to actor's onRequest handler
app.all("/actors/:id/:path{.*}", async (c) => {
    const actorId = c.req.param("id");
    const actorPath = (c.req.param("path") || "");

    // Forward to actor's onRequest handler
    const actor = client.counter.get(actorId);
    return await actor.fetch(actorPath, c.req.raw);
});

serve(app);

Connection & Lifecycle Hooks

onRequest will trigger the onBeforeConnect, onConnect, and onDisconnect hooks. Read more about lifecycle hooks.

Requests in flight will be listed in c.conns. Read more about connections.

WinterTC Compliance

The onRequest handler is WinterTC compliant and will work with existing libraries using the standard Request and Response types.

Limitations

• Does not support streaming responses & server-sent events at the moment. See the tracking issue.
• OPTIONS requests currently are handled by Rivet and are not passed to onRequest

API Reference

• RequestContext - Context for HTTP request handlers
• ActorDefinition - Interface for defining request handlers