Crate leptoskit_rpc

Expand description

It is the boundary between shared screens and the server. The same call runs during SSR, in the browser, and in a native guest; leptoskit_rpc_codegen turns the specification into TypeScript, Python, Go, Rust, Dart, and CLI clients.

A leptos server function is already a typed, isomorphic RPC: #[server] generates a struct whose FromArg/await call handles serialization, transport, and routing on both sides. What it leaves to you is everything around the call — retrying flaky networks, classifying which failures are worth retrying, and wrapping results so loading and failure states are one type. This crate adds exactly that layer:

[query] turns any server-fn call into a reactive Query with a retry policy, ready for <Await>-style rendering;
[mutation] and mutation_with_retry wrap calls in a leptos Action with the same error handling;
FnError classifies failures so “offline” and “your input was invalid” stop looking identical in the UI;
[query] and mutation declare operations that run on the database as the caller, called by their argument structs from every platform through [client::call] (features client, web, guest) and served at POST /api/<name> by [server::Server] (features server, db, and postgres or sqlite);
api publishes a server function to generated clients — the same RPC, described, with docs — so leptoskit rpc generate can write typed clients for TypeScript, Python, Go, Rust, Dart, and the command line (see the [spec] module, behind the ssr feature).

use leptos::prelude::*;
use leptoskit_rpc::FnError;
use leptoskit_rpc::RetryPolicy;
use leptoskit_rpc::mutation;
use leptoskit_rpc::query;

// Reads retry automatically and stay reactive.
let todos = query(RetryPolicy::aggressive(), || {
	async { list_todos().await.map_err(FnError::from) }
});

// Mutations only retry when asked, because re-sending a POST blindly is
// usually wrong.
let add = mutation(|title: &String| {
	let title = title.clone();
	async move { create_todo(title).await.map_err(FnError::from) }
});

§Publishing the RPC

Put #[api] above #[server] and the function becomes part of the app’s published RPC: a stable /api/<name> route, a JSON Schema description of its arguments and result, and its doc comment — including the # Arguments section — as documentation. #[api(internal)] keeps a function callable but takes it out of generated clients, and #[api(scope = Scope::PostsRead)] lets apps that sign in with yours call it with a token carrying that scope (see scopes!). Enable the ssr feature next to leptos/ssr, call leptoskit_rpc::spec::export_if_requested() first in main, and leptoskit rpc generate writes typed clients for any language that speak the RPC’s own protocol. See the book’s “Sharing the RPC” chapter.

Re-exports§

pub use scopes::ScopeInfo;
pub use scopes::Scopes;
pub use scopes::is_scope_name;

Modules§

live: The live protocol: the frames a client and a server exchange over a WebSocket, and the patches that keep a 2,000-message channel’s update at about one message’s size.
scopes: Typed OAuth scopes: what a third-party app may do with a person’s account once they let it sign in with yours.

Macros§

scopes: Declares an enum of OAuth scopes. Each variant names its scope and documents what it allows; the doc comment is what a consent screen shows.

Structs§

Backoff: How long a job waits before its next attempt: exponential, from min doubling up to max, each wait a random part of the upper half of that, so jobs that failed together don’t all return together.
CancelJob: Asks a job to stop: a waiting one never starts, and a running one sees cx.cancelled() at its next step. Only the person who enqueued it may.
Failed: What an on_failure mutation receives: the job’s arguments, and why it gave up.
Inbox: The signed-in person’s inbox: the newest notices, and how many are unread.
InboxArgs: Reads the signed-in person’s inbox: the query behind use_inbox.
InboxNotice: One notice in someone’s inbox.
JobOptions: How a job runs, from #[rpc::job(...)].
JobStatus: A job’s state and result, as a client reads it.
JobStatusArgs: The arguments of the job-status query: the job’s id.
MarkAllRead: Marks every notice in the signed-in person’s inbox read.
MarkRead: Marks one notice read.
Notice: What a notice says, and what tapping it does.
NoticeAction: A button on a notice: a mutation and its arguments. Tapping it runs the mutation as the person tapping, under their own policies.
Page: One page of a paginated query’s rows.
PageArgs: Which rows one page of a paginated query reads.
RetryPolicy: How a retrying call backs off between attempts.

Enums§

Error: Why an operation failed, as its body reports it.
FnError: One classified server-fn failure.
Kind: What kind of operation something is, which decides how it runs and how clients may call it.
NoticeKind: How a notice looks.
Visibility: Who may read a job besides the person who enqueued it, from #[rpc::job(visible_to = ...)].

Constants§

MAX_PAGE_ROWS: The most rows a page reads, whatever its limit asks for: the arguments come from the client.
MAX_PINNED_ROWS: The most rows a pinned page reads. It grows as rows are inserted into its range, so it gets room beyond MAX_PAGE_ROWS; past this, its oldest rows in page order are left off.

Traits§

Channel: One kind of channel: its join arguments, the messages it carries, and the presence each member shows.
Job: A job that runs in the background: the struct #[rpc::job] generates from the function’s arguments.
Operation: An operation’s arguments, as one value: the struct #[rpc::query] and #[rpc::mutation] generate from the function’s arguments, named in PascalCase.
Paginated: A query that reads a page at a time: the arguments carry a PageArgs, and the result is a Page. #[rpc::query] implements it for a query with a PageArgs argument that returns rpc::Page<T>.
Resumable: An item of a resumable stream: where the stream reached with it.
StreamOperation: A stream’s arguments, as one value: the struct #[rpc::stream] generates from the function’s arguments.

Functions§

call_with_retry: Calls fetch, retrying retryable failures under policy.
mutation: Wraps a server-fn call in a leptos action with unified errors.
mutation_with_retry: Wraps an idempotent server-fn call in a retrying action.
query: Turns a server-fn call into a reactive query under a retry policy.

Type Aliases§

Mutation: A reactive server-fn mutation.
Query: A reactive server-fn query: retrying, error-carrying, ready to render.
Result: What an operation’s body returns.
RetryFuture: The future returned by call_with_retry.

Attribute Macros§

action: Declares an action: an async fn that may call anything, published under its name.
api: Publishes a server function to generated clients.
channel: Declares a mutation: an async fn that writes in one transaction, published under its name.
cron: Enqueues an argument-less job on a schedule: a five-field cron expression in UTC, or @hourly, @daily, @weekly, @monthly, or @yearly.
job: Declares a job: work that runs later, in the background.
mutation
query: Declares a query: an async fn that reads, published under its name.
stream: Declares a stream: an async fn returning items over time, sent over the live connection only as fast as the client takes them.