Server Actions

Server actions let you write a Rust function that the build mirrors into a typed TypeScript function you can call from React - as a plain RPC, as a <form action> handler, or with useActionState. It's the mutation counterpart to #[handler]: use #[handler] to read the data a page needs, and a server action to do something (create, update, delete, submit a form).

Inspired by React/Next.js server actions, adapted for Ossido's Rust backend.

Mental model

Ossido is not React Server Components - there is no 'use server' server-reference mechanism. Instead the CLI generates a concrete, typed function per action into .ossido/actions.ts. Each generated function is a normal client function that POSTs to a conventional endpoint and hides the fetch, serialization and error handling. React never treats it as "special"; it simply matches the call signatures React expects.

Take this Rust action:

#[action]
async fn create_user(input: CreateUser) -> Result<Created, ActionError> {
  // ...
}

At build time the CLI turns it into a typed client function you import and call like any other - no fetch or serialization at the call site:

import { createUser } from '.ossido/actions';

const created = await createUser({ name, email }); // created: Created

In between, the #[action] macro registers an axum handler at POST /__ossido/action/<module>/create_user, and the CLI writes the matching createUser wrapper into .ossido/actions.ts - the POST, serialization and error handling all live inside it.

Everything React gives you for free once a function is wired into <form action> / useActionState - isPending, useFormStatus() - works, because the generated function is a real function.

Writing an action (Rust)

Actions live in actions.rs (or *.actions.rs) files anywhere under src/routes/. A single file can hold many actions.

// src/routes/newsletter/actions.rs
use ossido::{action, ActionError, Logger, Type};

#[Type]
pub struct Subscribe { pub email: String }

#[Type]
pub struct SubscribeResult { pub id: u64, pub email: String }

#[action]
pub async fn subscribe(input: Subscribe, logger: Logger)
    -> Result<SubscribeResult, ActionError>
{
    logger.info("subscribe action invoked");
    if !input.email.contains('@') {
        return Err(ActionError::message("Please enter a valid email address"));
    }
    Ok(SubscribeResult { id: 1, email: input.email })
}

The macro reads everything from the function signature (one source of truth). Arguments are classified like this:

• PrevState<T> - the previous useActionState value; its presence makes the action stateful.
• Files - uploaded files from a multipart submission (see File uploads).
• A parameter named logger - the framework Logger.
• The first remaining argument - the input, decoded from the request body.
• Any other argument - an ApplicationState field, matched by name (just like #[handler]).

Rules and requirements:

• The input and output types must be #[Type] (or #[Props]) structs so their TypeScript is generated and importable.
• The return type is either Result<T, ActionError> or a bare T. A bare return is treated as success.
• Input, state and logger arguments follow the same conventions as #[handler] and #[api], so state and logging work identically.

Naming the generated function

By default the generated TypeScript function takes the camelCased Rust name (create_user → createUser). To pick the name yourself, pass it to the macro - either a bare identifier or a string literal:

#[action(registerUser)]        // or #[action("registerUser")]
pub async fn create_user(input: CreateUser) -> Result<Created, ActionError> { ... }

import { registerUser } from '.ossido/actions';

Stateful actions (useActionState)

Add a PrevState<T> first parameter to receive the previous state. React round-trips it on every submit; PrevState::get() is None on the first render.

use ossido::{action, PrevState, Type};

#[Type]
pub struct FormState { pub ok: bool, pub message: String, pub attempts: u32 }

#[action]
pub async fn submit_signup(prev: PrevState<FormState>, input: Subscribe) -> FormState {
    let attempts = prev.get().map(|s| s.attempts + 1).unwrap_or(1);
    if !input.email.contains('@') {
        return FormState { ok: false, message: "Invalid email".into(), attempts };
    }
    FormState { ok: true, message: format!("Subscribed {}", input.email), attempts }
}

PrevState<T> is client-supplied and round-tripped verbatim - treat it as untrusted input, never as authorization state.

Calling an action (React)

The build generates one importable function per action into .ossido/actions.ts, named the camelCased Rust name by default (create_user → createUser) or whatever you passed to #[action(...)]. It works in three ways - all against the same generated function. Import the runtime helpers from @ossido-labs/ossido/actions.

1. Imperative (typed RPC)

import { subscribe } from '.ossido/actions';

const result = await subscribe({ email: 'ada@example.com' });
//    ^ SubscribeResult                ^ typed input

2. <Form> - progressive enhancement

<Form> renders a real <form method="post" action={endpoint}>. When hydrated, submission is intercepted and the action is called with the form's FormData; with JS disabled, the browser does a native POST and the server replies with a 303 Post/Redirect/Get.

import { Form } from '@ossido-labs/ossido/actions';
import { subscribe } from '.ossido/actions';

<Form action={subscribe}>
  <input name="email" type="email" />
  <button type="submit">Subscribe</button>
</Form>;

React's own <form action={fn}> also works when hydrated, but has no no-JS fallback (there's no URL). Use <Form> when you want progressive enhancement.

3. useActionState

Pass a stateful action (one with a PrevState<T>) straight to useActionState. You get back [state, formAction, isPending]; isPending and useFormStatus() come for free from React.

import { useActionState } from '@ossido-labs/ossido/actions';
import { submitSignup } from '.ossido/actions';
import type { FormState } from '@ossido-labs/ossido/types';

const INITIAL: FormState = { ok: false, message: '', attempts: 0 };

function Signup() {
  const [state, formAction, isPending] = useActionState(submitSignup, INITIAL);
  return (
    <form action={formAction}>
      <input name="email" type="email" />
      <button disabled={isPending}>
        {isPending ? 'Submitting...' : 'Sign up'}
      </button>
      {state.message && (
        <p>
          {state.message} (attempt {state.attempts})
        </p>
      )}
    </form>
  );
}

File uploads (multipart)

Actions accept file uploads through a Files parameter - recognized by the macro just like PrevState and logger, and excluded from the generated TypeScript input type. Text fields still decode into your #[Type] input; files arrive separately via Files.

use ossido::{action, ActionError, Files, Type};

#[Type]
pub struct UploadMeta { pub title: String }

#[action]
pub async fn upload_avatar(input: UploadMeta, files: Files) -> Result<Uploaded, ActionError> {
    let file = files
        .get("avatar")
        .ok_or_else(|| ActionError::message("an avatar file is required"))?;
    save(file.bytes()).await; // filename(), content_type(), bytes(), len(), into_bytes()
    Ok(/* ... */)
}

A Files value is a map of form-field name → uploaded files, and each UploadedFile carries its bytes plus metadata. The full surface you have to work with:

impl Files {
    fn get(&self, name: &str) -> Option<&UploadedFile>; // first file under `name`
    fn get_all(&self, name: &str) -> &[UploadedFile];   // all of them (multiple input)
    fn contains(&self, name: &str) -> bool;
    fn is_empty(&self) -> bool;
    fn names(&self) -> impl Iterator<Item = &str>;      // fields that carried a file
}

impl UploadedFile {
    fn filename(&self) -> &str;             // client-provided name
    fn content_type(&self) -> Option<&str>; // declared content type, if any
    fn bytes(&self) -> &[u8];               // borrow the bytes
    fn len(&self) -> usize;                 // size in bytes
    fn is_empty(&self) -> bool;
    fn into_bytes(self) -> Vec<u8>;         // consume, take ownership of the bytes
}

An action can also take only Files, with no text input.

On the client it's automatic. The generated function inspects what you pass and picks the encoding:

• a FormData that contains file entries → multipart/form-data (the browser sets the boundary);
• a text-only FormData → URL-encoded;
• a plain object → JSON.

So the imperative call and <Form> you already use just work. For the no-JS form path, set the encoding explicitly so the native POST is multipart:

<Form action={uploadAvatar} encType="multipart/form-data">
  <input name="title" />
  <input name="avatar" type="file" />
  <button type="submit">Upload</button>
</Form>

Files come through the separate Files param rather than as fields on the #[Type] input because multipart text fields are strings coerced through serde, which raw file bytes can't round-trip through. Keeping them separate lets both decode cleanly and keeps the generated TypeScript input file-free.

Error handling

There are two distinct failure channels:

• Expected, typed errors - return Err(ActionError). The response is 422 { "error": { message, fields? } }.
  • An imperative call throws OssidoActionError (with .message and optional .fields) - catch it with try/catch.
  • In a form or useActionState flow, prefer modelling recoverable errors inside the returned state (Ok(FormState { ok: false, ... })) so they land in state instead of throwing.
• Unexpected panics - caught by the framework, surfaced through the same dev error overlay as any handler panic, and returned as a detail-free 500 in production.

Err(ActionError::message("Please enter a valid email address"))
// or with per-field messages:
Err(ActionError::with_fields("Validation failed", fields))

import { OssidoActionError } from '@ossido-labs/ossido/actions';

try {
  await createUser(input);
} catch (e) {
  if (e instanceof OssidoActionError) console.log(e.message, e.fields);
}

The @ossido-labs/ossido/actions package

• Form - a <form> wired to an action with progressive enhancement.
• useActionState - re-export of React's hook (one import site).
• useFormStatus - re-export of React DOM's hook.
• OssidoActionError - the error thrown on a failed action call (.message, .fields).
• createAction / createStatefulAction - factories used by the generated actions.ts (rarely called directly).
• ActionError, ActionFn, StatefulActionFn - types.

The Rust side exports action, ActionError, PrevState, Files, UploadedFile and ActionInputError from the ossido crate.

How it works (reference)

Endpoint. Each action is registered at:

POST /__ossido/action/<module>/<fn_name>

where <module> is the action file's route path, mangled to a single safe segment (newsletter/actions.rs → newsletter_actions). It's always a POST - the "verb" is the function name.

Wire protocol (x-ossido-action-version: 1). One endpoint serves two callers, chosen by request headers:

• Hydrated (generated fetch): sends x-ossido-action: 1. The body is application/json { "input": <I>, "__ossido_prev_state"?: <P> }, a URL-encoded form, or multipart/form-data when the FormData carries files. The response is { "data": <T> } or { "error": <ActionError> }.
• No-JS native form POST: URL-encoded or multipart/form-data body, Accept: text/html, no marker header → a 303 redirect back to the referring page.

Multipart bodies are parsed once, from the buffered request body, with multer (the same crate axum uses) into a single decoded form that yields the typed input, PrevState and Files together - so a large body isn't parsed twice.

Codegen. On every .rs change the CLI regenerates:

• .ossido/main.rs - module declarations and POST routes for every action.
• .ossido/actions.ts - one typed exported function per action.
• .ossido/types.ts - the #[Type] structs, importable from @ossido-labs/ossido/types.

You never edit the .ossido/ directory.

Limitations & notes

• Upload size isn't bounded yet - the request body is buffered with no size cap (inherited from the #[api] POST path), so a configurable limit is a sensible follow-up before accepting uploads from untrusted clients.
• Middleware / auth - actions are registered at the router top level, so a directory-level middleware.rs does not automatically wrap them yet. Authentication and CSRF for actions are a planned follow-up; the x-ossido-action header guards the JSON path, but the no-JS form path still needs a real CSRF token.
• Client-only - generated functions use a relative fetch; they're client-interaction primitives and are not meant to be called during SSR.
• Redirects - the no-JS success path redirects back to the referrer; an explicit "redirect to X after success" is a planned addition.

Quick reference

// Rust - src/routes/**/actions.rs
#[action]
async fn my_action(input: In, /* state, logger */) -> Result<Out, ActionError> { ... }

#[action]
async fn my_form(prev: PrevState<State>, input: In) -> State { ... }   // useActionState

#[action]
async fn my_upload(input: In, files: Files) -> Result<Out, ActionError> { ... }  // multipart

// React - my_action → myAction, my_form → myForm (camelCased by default)
import { myAction, myForm } from '.ossido/actions'
import { Form, useActionState, OssidoActionError } from '@ossido-labs/ossido/actions'

// imperative
await myAction(input)
// progressive enhancement
<Form action={myAction}> ... </Form>
// stateful
const [state, formAction, isPending] = useActionState(myForm, initial)