Arri RPC

In Arri RPC, every procedure receives an Event type. This type is passed to every procedure and allows access to request-specific context. To use a custom event, you must implement the arri.Event interface, which requires Request() *http.Request and Writer() http.ResponseWriter methods.

When initializing your app with arri.NewApp, you provide a factory function that creates your custom event using the incoming http.ResponseWriter and *http.Request.

type MyCustomEvent struct {
    r *http.Request
    w http.ResponseWriter
}

func (e MyCustomEvent) Request() *http.Request {
    return e.r
}

func (e MyCustomEvent) Writer() http.ResponseWriter {
    return e.w
}

// In main:
app := arri.NewApp(
    http.DefaultServeMux,
    arri.AppOptions[MyCustomEvent]{},
    func(w http.ResponseWriter, r *http.Request) (*MyCustomEvent, arri.RpcError) {
        return &MyCustomEvent{r: r, w: w}, nil
    },
)

Arri uses a file-based routing system where procedure endpoints are derived from their file paths and names.

Routing Rules:

• Endpoints are converted to kebab-case (e.g., getStatus.rpc.ts becomes /get-status).
• Directory structures are preserved in the URL (e.g., src/procedures/users/getUser.rpc.ts becomes /users/get-user).
• All paths are relative to the rpcRoutePrefix option.

HTTP Methods:

• By default, all procedures use the post method.
• You can override the method using the method option in defineRpc.
• Supported methods: post, get, delete, patch, put.

Special Note on GET requests: When using the get method, RPC parameters are mapped as query parameters and coerced using a.coerce from arri-validate. While scalar types are supported, arrays and nested objects are not supported for get methods.

// procedures/users/getUser.rpc.ts
export default defineRpc({
    method: 'get',
    // rest of config
});

For maximum performance, use a.compile(schema) to create a highly optimized validator. The compiled validator implements the standard-schema interface.

Important Constraints:

• Environment: Compiled validators use new Function() and will not work in a browser environment. They are intended for backend servers.
• Performance: Compilation has overhead, so compile each schema only once.
• Code Generation: To access the generated function bodies (e.g., for debugging or custom logic), pass true as the second argument to a.compile(schema, true). This is disabled by default to save memory.

Compiled Methods:

• validate(input)
• parse(input)
• parseUnsafe(input)
• coerce(input)
• coerceUnsafe(input)
• serialize(input)
• serializeUnsafe(input)

const User = a.object({
    id: a.string(),
    email: a.nullable(a.string()),
    created: a.timestamp(),
});

const $$User = a.compile(User);

$$User.validate(someInput);
$$User.parse(someJson);
$$User.coerce(someObject);
$$User.serialize({ id: '1', email: null, created: new Date() });

// Accessing generated code (requires second param true)
const $$UserWithCode = a.compile(User, true);
console.log($$UserWithCode.compiledCode.validate);

The Arri server automatically generates a __definition.json file which serves as the API schema for all procedures and models. This schema is used by Arri to generate type-safe clients in multiple languages. It uses a superset of JSON Type Definition for models rather than standard JSON Schema to ensure better cross-language code generation.

By default, you can view this schema at the /__definition endpoint while the server is running. Note that this endpoint is relative to your configured rpcRoutePrefix.

{
    "procedures": {
        "sayHello": {
            "transport": "http",
            "path": "/say-hello",
            "method": "post",
            "params": "SayHelloParams",
            "response": "SayHelloResponse"
        }
    },
    "definitions": {
        "SayHelloParams": {
            "properties": {
                "name": {
                    "type": "string"
                }
            }
        }
    }
}

To prevent crashes when the server's data model changes, Arri clients should be tolerant. Instead of failing validation, clients should assign fallback values for missing or unrecognized fields.

Fallback Value Mapping:

When to return an error instead of falling back:

• Unable to connect to the server.
• Server returned an error.
• Server did not provide the correct content-type header.
• Server response is not correctly formatted JSON.