RFC: Server Function Serialization And Hydration #777

leonidaz · 2026-03-02T02:47:47Z

leonidaz
Mar 2, 2026
Maintainer

RFC: Server Function Serialization And Hydration

Status: Draft
Authors: Ripple Core (proposed)
Created: 2026-03-01
Discussion: TBD

Summary

This RFC proposes a unified model for:

Serializing #server exported function results during SSR and consuming that
payload during client hydration.
Using hash-addressed RPC transport for server function calls.
Adding server-side and cross-request caching using a stable
file + function + args hash key.
Defining explicit behavior and diagnostics for universal async functions used
in components.
Adding argument validation hooks for #server functions (TypeScript-informed
and schema-based).

The goal is to improve TTFB-to-interactive continuity and make server/client
execution semantics explicit and safe.

Serialization and hydration in this proposal use devalue.stringify(...) and
devalue.parse(...).

Motivation

Current SSR + hydration flow does not provide explicit protocol negotiation for
#server function calls. The same function may run:

Once during SSR.
Again during client hydration or immediate client interaction.

This can create state divergence if client-side cached results drift from server
state. In addition, universal async functions (plain async functions reachable
from components) can create ambiguity about where execution happens. Finally,
server function arguments need consistent runtime validation to avoid
trust-by-annotation problems.

Goals

Keep server function result caching on the server side.
Hydrate precomputed #server function results from SSR into client runtime.
Use a deterministic cache key based on module identity, export name, and
canonicalized args.
Use hash-addressed RPC calls (/_$_ripple_rpc_$_/<function_hash>) for server
function invocation.
Negotiate wire protocol by sending client-supported serialization metadata in
generated RPC calls and letting the server choose a compatible response version.
Introduce configurable cache invalidation and TTL controls.
Provide compile-time diagnostics for unsafe universal async usage.
Provide runtime validation hooks for #server function parameters.

Non-Goals

Full offline cache storage strategy (Service Worker/IndexedDB) in this RFC.
Replacing the current /_$_ripple_rpc_$_/<function_hash> transport in this RFC.
Arbitrary closure serialization for function arguments/results.
Persistent client-side server-function result caching beyond one-time hydration
payload consumption.

Terminology

Server function: Named export inside a #server block callable from compiled
component code.
Universal function: A plain function declared in module scope that may run on
server and client depending on usage.
Hydration payload: Data serialized into SSR HTML for client hydration bootstrap.
Cache key: Stable hash derived from module_id + export_name + args.

Detailed Proposal

1. SSR Serialization and Client Hydration for `#server` Exports

1.1 Compile-time transform

Compiler already emits a module-scoped server object (_$_server_$_) for
#server exports in both client and server compilations. This RFC builds on that
existing mechanism.

In server compilation, _$_server_$_.<name> points to the real server function
implementation via a generated wrapper.
In client compilation, _$_server_$_.<name> is an RPC stub that calls
_$_.rpc(function_hash, args, protocol).

Server wrapper responsibilities:

Receive original call arguments.
Run useValidation(...) before user logic.
Compute function/args/cache hashes.
Check server cache and return cached value when present.
On miss, call the user-authored function body and store/register the result.

Server-side cache checks in this RFC happen at this module-object boundary (inside
generated _$_server_$_ function properties), rather than via a separate global
callsite transform.

Illustrative shape:

_$_server_$_.<export_name>(...args)

During SSR, if the call executes successfully, runtime stores the result in an SSR
hydration object keyed by cache key.

1.2 Script payload format

SSR emits one script block per server function call result (streaming-friendly),
using the cache hash in the script id:

<script id="__ripple_server_data_<cache_hash>" type="application/json">
  { "v": 1, "encoding": "devalue@5", "payload": "<devalue.stringify(entry)>" }
</script>

Requirements:

v is payload schema version.
encoding identifies serialization format (devalue@5).
payload is the serialized output of devalue.stringify(entry).
each script contains one result envelope:
- success: { "ok": true, "value": <serializable> }
- failure: { "ok": false, "error": { "code": string, "message": string } }
the outer JSON and embedded payload string must be escaped for script-safe HTML
output.
script id format is: __ripple_server_data_{cache_hash}.

Serialization options:

runtime calls devalue.stringify(entry, reducers) and
devalue.parse(payload, revivers).
reducers/revivers come from global config plus function-level overrides.

1.3 Client behavior

At runtime, generated client _$_server_$_.<export_name>(...args) stubs perform a
one-time hydration payload lookup first, then fall back to RPC. Client runtime
does not keep a persistent in-memory result cache.

Hydration lookup flow:

Derive cache_hash from function_hash + serialized_args_hash.
Read <script id="__ripple_server_data_{cache_hash}"> if present.
Parse envelope JSON and restore entry via devalue.parse(payload, revivers).
Consume and remove the script node after successful parse.
Return hydrated value immediately for that call.
If no hydration payload exists, perform RPC request.

The generated RPC call includes protocol negotiation metadata hard-coded at client
build time:

version (for example 1) for wire envelope schema.
acceptEncodings (for example ['devalue@5']) for supported decode formats.

The server chooses an appropriate response version/encoding and returns those in
the response envelope.

RPC response bodies also use devalue.stringify(result, reducers) on the server
and devalue.parse(result_payload, revivers) on the client.

In server compilation, generated _$_server_$_.<export_name>(...args) wrappers
perform the same cache-key lookup against module-level server cache before
executing the function body.

1.4 Custom serializer/parser extension points

Ripple exposes devalue-compatible extension points for custom types.

Config shape:

export default defineConfig({
  serialization: {
    reducers: {
      Vector: (value) => value instanceof Vector && [value.x, value.y],
    },
    revivers: {
      Vector: ([x, y]) => new Vector(x, y),
    },
  },
});

Contract:

reducers map is passed as second argument to devalue.stringify(...).
revivers map is passed as second argument to devalue.parse(...).
a reducer function that returns a truthy value is treated as a type match
(devalue semantics).
reducer/reviver names must match exactly and are case-sensitive.

Safety rules:

reducers/revivers must be deterministic and side-effect free.
revivers execute on both server and client hydration paths and therefore must
not depend on server-only globals.
in dev mode, missing reviver for a serialized custom type throws with actionable
diagnostics.

Merge order:

Ripple built-in reducers/revivers.
Global reducers/revivers from ripple.config.ts.
A custom devalue is imported from a ripple module where reducers and revivers
will be injected when calling the original devalue.

Later entries override earlier entries by key.

2. Cache Key and Hash Strategy

2.1 Canonical key input

The key material is:

<normalized_module_id>::<export_name>::<canonical_args_devalue>::<schema_version>

normalized_module_id: build-stable module reference (Vite/Rollup normalized
path or virtual module id).
export_name: exact #server export identifier.
canonical_args_devalue: deterministic serialization using
devalue.stringify(...) after key canonicalization:
- object keys sorted lexicographically
- stable number formatting
- devalue support for undefined, Date, Map, Set, and cyclical
  structures
- uses the same configured reducer map used for transport serialization
schema_version: server cache schema version (allows invalidation on wire
format change).

To avoid key drift, both server and client must use identical reducer
configuration for key material.

2.2 Hash algorithm

Default hashing primitive: SHA-256.
Encoding requirement: deterministic string output. Base64 is not required.
Hash creation must be delegated to the configured server adapter.
Compiler/runtime must not compute hashes directly.
Compatibility default for adapter-provided RPC function ids: hex encoding with
truncation, matching current implementation:

adapter.createFunctionHash(func_path); // equivalent default: sha256(func_path).hex.slice(0, 8)

Cache-key hash creation is also adapter-owned:
- adapter.createCacheKeyHash(cache_input)
- adapter controls encoding (hex or base64url) and truncation policy
Recommended adapter defaults:
- hex (default): sha256(input).digest('hex'), optionally truncated
- base64url (optional): shorter URL-safe form
Optional dev mode: append debug suffix for inspectability.

fh_<adapter.createFunctionHash(func_path)>
rk_<adapter.createCacheKeyHash(cache_input)>

2.3 Collision handling

Collisions are treated as improbable but guarded:

In dev mode, store debug_input for mismatches and warn loudly.
In prod, rely on hash robustness.

3. RPC Transport: Hash-Addressed POST Endpoint

3.1 Transport shape

Current runtime transport is POST to a hash-addressed endpoint.

URL shape example:

/_$_ripple_rpc_$_/<function_hash>

Where function_hash is the server function route id derived from
<file_path>#<export_name>.

Headers:

Content-Type: application/json

Body:

devalue.stringify({ args, protocol: { version, acceptEncodings } })

Client does not send a cache key. The server computes its cache key internally
from function identity plus request arguments.

Protocol negotiation contract:

Generated client code hard-codes protocol fields during build.
Client sends protocol.version and protocol.acceptEncodings with every RPC
call.
Server selects response.version and response.encoding from supported
options.
If no compatible encoding/version exists, server returns structured error
UNSUPPORTED_PROTOCOL.

3.2 RPC policy

All server function RPC calls go through _$_.rpc(function_hash, args, protocol).

Proposed function-level directive options:

#server {
  export async function getUser(id: string) {
    "use cache: timeout 5000";
    // ...
  }
}

"use cache: timeout <ms>"; implies idempotent read semantics.
The timeout settings may also be added to ripple.config.ts which would affect
all #server block functions:

export default defineConfig({
  // or serverBlock
  serverFunctions: {
    cache: {
      timeout: 5000,
    },
  },
});

3.3 Security and limits

Enforce request-size limits for POST body and response payload.
Apply auth/session checks identical to current server function handling.
Prevent sensitive argument leakage:
- allow redaction hooks for logs
If a request-size limit is exceeded, fail with structured error
REQUEST_TOO_LARGE and appropriate HTTP status (413 for body overflow).

Recommended size-related config:

transport.maxFunctionHashBytes: maximum <function_hash> length in the RPC
path segment.
transport.maxRequestBodyBytes: maximum byte length of
devalue.stringify({ args, protocol }).
serialization.maxRpcResponseBytes: maximum serialized RPC response size.
serialization.maxHydrationScriptBytes: maximum SSR hydration script payload
size.
cache.maxEntryBytes: maximum per-entry serialized cache size.
cache.maxTotalBytes: maximum server in-memory cache footprint per module.

export default defineConfig({
  serverFunctions: {
    transport: {
      method: 'post',
      maxFunctionHashBytes: 64,
      maxRequestBodyBytes: 64 * 1024,
    },
    serialization: {
      maxRpcResponseBytes: 256 * 1024,
      maxHydrationScriptBytes: 512 * 1024,
    },
    cache: {
      timeout: 5000,
      maxEntryBytes: 128 * 1024,
      maxTotalBytes: 2 * 1024 * 1024,
    },
  },
});

4. `#server` Block Caching

4.1 Module-level in-memory cache

Server runtime keeps a per-module map:

Map<cache_key, { value: unknown; expires_at: number | null; tags?: string[] }>;

Behavior:

On function call, if unexpired entry exists, return cached value.
Otherwise compute, validate, store, return.

4.2 Cross-request persistence (optional)

Add ripple.config.ts cache provider interface:

export default defineConfig({
  serverFunctions: {
    cache: {
      strategy: 'memory' | 'adapter',
      schemaVersion: 1,
      defaultTtlMs: 0,
    },
  },
});

Adapters may back this with Redis/KV, but this RFC only standardizes the runtime
contract.

4.3 Invalidation controls

Config-level invalidation:

serverFunctions: {
  serialization: {
    schemaVersion: 1,
    reducers: {},
    revivers: {},
  },
  cache: {
    schemaVersion: 2,
    buildSalt: process.env.RIPPLE_CACHE_SALT,
  }
}

Function-level invalidation via directives:

"use cache-timer: 5000" for TTL.
Future extension: "use cache-tag: user".

Page refresh behavior:

If same key and unexpired data exists in server cache, return cached response.
Client always re-requests via RPC after hydration; no client-side result reuse
is performed.

5. Universal Functions: Semantics and Diagnostics

5.1 Problem

Plain async functions in component scope can be used in SSR render and also in
client effects/handlers, creating uncertainty about environment and timing.

5.2 Compiler warnings

Emit warning when compiler detects:

await/Promise-consuming call in render-reachable component code.
No explicit environment boundary (#server, client-only effect/handler, or
guarded branch).

Do not emit this warning for async usage inside effect(...) or event handlers.
Those paths are client-only, are not compiled into SSR server execution, and
therefore are out of scope for this server/client ambiguity diagnostic.

Do not emit this warning for async calls that are explicitly environment-guarded
by if (import.meta.env.SSR) { ... } or if (!import.meta.env.SSR) { ... }.
These branches are environment-specific by construction and do not represent
ambiguous universal execution.

Diagnostic message (proposed):

Async universal function used in render path may execute in both server and client.
Use a #server export for data-fetching or guard execution by environment.

5.3 Environment behavior

effect(...) and event handlers are client-only and must not execute on SSR.
SSR render path should not execute client-only hooks.
For universal function use in SSR, runtime may optionally resolve via fetch if
explicitly configured, but default guidance is to migrate data access to
#server exports.

5.4 Diagnostic scope exclusion

Async function calls within effect(...) callbacks are excluded from
universal-async SSR warnings.
Async function calls within event handlers (for example, onclick, oninput)
are excluded from universal-async SSR warnings.
Async function calls inside if (import.meta.env.SSR) branches are excluded
from universal-async SSR warnings.
Async function calls inside if (!import.meta.env.SSR) branches are excluded
from universal-async SSR warnings.
The warning only applies to render-reachable code paths that are emitted into
server output.

6. Validation Model for `#server` Function Arguments

6.1 Validation hook

Require each #server function to call useValidation(schema, argsObject) as the
first executable statement.

Example:

#server {
  import { useValidation } from "ripple/server";
  import { z } from "zod";

  const searchUsersSchema = z.object({
    query: z.string().min(1),
    limit: z.number().int().min(1).max(100),
  });

  export async function searchUsers(query: string, limit: number) {
    const { query: q, limit: l } = useValidation(searchUsersSchema, { query, limit });
    // ...
  }
}

Compiler/runtime contract:

useValidation(...) must be present as the first executable statement in each
exported #server function.
Validate args before function body logic executes on every entry point (SSR
invocation and RPC invocation).
If a #server export does not satisfy the useValidation(...) rule, emit a
compiler error in strict mode (default).
On validation failure, return structured error envelope with
code: "VALIDATION_ERROR".

Canonical input contract:

For cross-library consistency, useValidation should receive an object
containing all arguments ({ query, limit }).
The schema validates that one object value, and the function uses only
parsed/validated output.
This avoids brittle per-library introspection of positional argument coverage
while preserving ergonomic function signatures.

6.2 Third-party schema integration (required)

TypeScript types alone are not sufficient at runtime.

Ripple should not implement its own validation engine. Instead, it should accept
third-party schema objects.

Proposed schema contract:

Any schema object with a runtime parser API is supported (for example parse,
safeParse, or equivalent).
useValidation(...) performs runtime parsing and returns validated data.
Compiler responsibility is structural only:
- ensure useValidation(...) exists as first executable statement
- ensure schema symbol resolves
- ensure args object shape is provided

useValidation conceptual signature:

function useValidation<T>(schema: unknown, input: unknown): T;

Config:

serverFunctions: {
  validation: {
    mode: "schema-required",
    onMissingSchema: "error"
  }
}

Recommended default: schema-required in all environments.

6.3 Enforcement behavior

If a #server function is exported but lacks a valid first-statement
useValidation(...) call, compilation fails (default policy).
If useValidation schema/input arguments are invalid or unresolved, compilation
fails.
If runtime validation throws unexpectedly, map to VALIDATION_INTERNAL_ERROR.
Only validated argument values are passed to the server function implementation.

6.4 How to enforce coverage across different libraries

Do not attempt deep semantic equivalence checks across all third-party schema
libraries.
Enforce structural invariants that are library-agnostic:
- first executable statement must be a useValidation(schema, argsObject) call
- schema symbol must resolve
- argsObject must be object-like and include declared function arguments
  (directly or via spread from validated source)
Enforce semantic coverage at runtime via useValidation(...) parse result, not
via compile-time schema introspection.

7. Error and Serialization Constraints

7.1 Serializable value contract

Hydration and RPC payload values must be serializable by devalue.stringify(...)
and restorable by devalue.parse(...).

Non-serializable values (function, symbol, cyclical object without encoder)
produce:

compiler hint where static analysis can detect it
runtime error envelope where dynamic only

Custom-type mismatch behavior:

reducer exists but reviver missing: hydration/RPC decode error with
SERIALIZATION_REVIVER_MISSING.
reducer output shape invalid for reviver: decode error with
SERIALIZATION_REVIVER_INVALID_INPUT.
unknown custom type tag in payload: decode error with
SERIALIZATION_UNKNOWN_TYPE.

7.2 Error transport

Do not serialize full stack traces to client by default.

Return envelope:

{ "ok": false, "error": { "code": "INTERNAL_ERROR", "message": "..." } }

Dev mode may include stack under gated flag.

Compiler and Runtime Implementation Sketch

Compiler

Detect #server exported functions and annotate metadata table (module_id,
export, directives).
Emit module-scoped _$_server_$_ object for both client/server builds and
inject cache checks at generated function-property wrappers.
In server builds, split user-authored bodies from generated wrappers that
perform validation, hash generation, cache lookup, and miss execution.
Emit diagnostics for universal async ambiguity.

Server runtime

Implement deterministic key builder and canonical serializer.
Call adapter-provided hash creators for function hash and cache-key hash
generation.
Maintain module-level cache and TTL checks.
Emit SSR payload script during SSR (without enabling client result caching).
Serve hash-addressed RPC endpoint (/_$_ripple_rpc_$_/<function_hash>).

Client runtime

Attempt one-time hydration payload consumption by script id before RPC.
Send generated protocol metadata (version, acceptEncodings) with every RPC
call.
Do not keep a persistent cache of server function results on client.
Decode server-selected response encoding/version and return value directly.

Backward Compatibility and Migration

Keep current /_$_ripple_rpc_$_/<function_hash> endpoint shape.
Existing deployments should enforce configured request/response size limits.

Alternatives Considered

GET query transport (h/k/a) with client-supplied cache key: not chosen for
current implementation alignment.
SSR payload in HTML comments instead of script JSON: rejected due to complexity
and parsing overhead.
Type-only validation: rejected because TS types are erased at runtime.

Open Questions

What are sane default limits for request body/response/hydration payload sizes
across common deployments?
What is the canonical serializer spec for special JS types and bigint
precision?
Which adapter-level cache API should be standardized first (KV-like vs
fetch-like)?
Should Ripple publish helper docs/examples for common schema libs (Zod,
Valibot, ArkType) in v1?

Rollout Plan

Land internal key serializer + hydration payload behind feature flag.
Keep current hash-addressed POST transport and enforce explicit
request/response size-limit config.
Land schema-required validation enforcement via useValidation(...).
Stabilize ripple.config.ts schema and remove feature flag.

Appendix: Full Concrete Example

This example uses the provided source and generated server/client output shape,
and adds the RFC runtime logic for validation, serialization, transport protocol
negotiation, and server-side cache lookup by key.

A. Source module

#server {
  import { useValidation } from 'ripple/server';
  import { z } from 'zod';

  const getEmailSchema = z.object({ id: z.number().int().positive() });

  export async function get_email(id: number): Promise<string> {
    const { id: validated_id } = useValidation(getEmailSchema, { id });
    const response = await fetch('https://dummyjson.com/users/' + validated_id);
    const data = await response.json();
    return data['email'];
  }
}

export component App() {
  const email = await #server.get_email(1);
  <div>{email}</div>
}

B. Server compilation shape with RFC runtime logic

export const _$_server_$_ = (() => {
  var _$_server_$_ = {};

  // Module-level server cache map: key -> { ok, value, expires_at }
  const __server_fn_cache = new Map();

  // User-authored body extracted from #server block.
  async function __user_get_email(validated_id) {
    const response = await fetch('https://dummyjson.com/users/' + validated_id);
    const data = await response.json();
    return data['email'];
  }

  _$_server_$_.get_email = async function get_email(id) {
    // Generated wrapper: validation, hashing, server cache, then user fn.
    // Required validation hook (first executable statement)
    const { id: validated_id } = _$_.useValidation(getEmailSchema, { id });

    // Adapter-owned key creation from function-hash + serialized-args-hash
    const function_hash = '4c57113b'; // file + function identity hash
    const serialized_args = devalue.stringify([validated_id]);
    const args_hash = _$_.adapter.createArgsHash(serialized_args);
    const cache_hash = _$_.adapter.createCacheKeyHash(
      `${function_hash}::${args_hash}`,
    );

    // Server cache hit
    const cached = __server_fn_cache.get(cache_hash);
    if (
      cached &&
      (cached.expires_at === null || cached.expires_at > Date.now())
    ) {
      return { value: cached.value, cache_hash };
    }

    // Execute user function body on cache miss
    const value = await __user_get_email(validated_id);

    // Server cache store
    __server_fn_cache.set(cache_hash, {
      ok: true,
      value,
      expires_at: Date.now() + 5000,
    });

    // Register entry for hydration script emission during SSR
    _$_.register_server_cache_entry(cache_hash, { ok: true, value });

    return { value, cache_hash };
  };

  return _$_server_$_;
})();

export async function App(__output) {
  return _$_.async(async () => {
    _$_.push_component();

    const { _$_value: value, _$_cache_hash: cache_has } =
      await _$_server_$_.get_email(1);
    const data = _$_value;
    __output.push(`<div>${_$_.escape(data)}</div>`);

    // SSR emits one script per function call using cache-hash id
    const entry = _$_.consume_registered_server_cache_entry(_$_cache_hash);
    const payload = devalue.stringify(entry);
    __output.push(
      `<script id="__ripple_server_data_${_$_cache_hash}" type="application/json">` +
        JSON.stringify({ v: 1, encoding: 'devalue@5', payload }) +
        '</script>',
    );
  });
}

C. Client compilation shape with RFC runtime logic

var _$_server_$_ = {
  get_email(...args) {
    // Generated client protocol metadata is hard-coded at build time.
    return _$_.rpc('4c57113b', args, {
      version: 1,
      acceptEncodings: ['devalue@5'],
    });
  },
};

export function App(__anchor, _, __block) {
  _$_.async(async () => {
    _$_.push_component();

    const data = (
      await _$_.maybe_tracked(
        _$_.with_scope(__block, async () => _$_server_$_.get_email(1)),
      )
    )();

    // ...the rest of the component
  });
}

D. Client runtime hydration + rpc protocol negotiation

import * as devalue from 'devalue';

export async function rpc(function_hash, args, protocol) {
  const serialized_args = devalue.stringify(args);
  const args_hash = _$_.adapter.createArgsHash(serialized_args);
  const cache_hash = _$_.adapter.createCacheKeyHash(
    `${function_hash}::${args_hash}`,
  );

  // One-time hydration handoff: consume SSR payload if present.
  const script_id = `__ripple_server_data_${cache_hash}`;
  const script_node = document.getElementById(script_id);
  if (script_node?.textContent) {
    const script_envelope = JSON.parse(script_node.textContent);
    const hydrated_entry = devalue.parse(script_envelope.payload);
    script_node.remove();

    if (hydrated_entry.ok) {
      return hydrated_entry.value;
    }

    throw new Error(hydrated_entry.error?.message ?? 'Hydrated server error');
  }

  const request_body = devalue.stringify({
    args,
    protocol: {
      version: protocol.version,
      acceptEncodings: protocol.acceptEncodings,
    },
  });

  // Actual rpc transport shape: POST /_$_ripple_rpc_$_/<function_hash>
  const res = await fetch(`/_$_ripple_rpc_$_/${function_hash}`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: request_body,
  });

  if (!res.ok) {
    throw new Error(`Server function call failed with status ${res.status}`);
  }

  const text = await res.text();
  const envelope = devalue.parse(text);

  if (
    envelope.version !== protocol.version ||
    !protocol.acceptEncodings.includes(envelope.encoding)
  ) {
    throw new Error('Server returned unsupported protocol encoding/version');
  }

  return envelope.value;
}

E. End-to-end sequence

SSR calls _$_server_$_.get_email(1).
useValidation(getEmailSchema, { id }) validates input before logic runs.
Server computes cache_hash through adapter and checks module cache.
On miss, server fetches email, stores cache entry, registers hydration entry.
SSR writes <script id="__ripple_server_data_{cache_hash}"> with
devalue.stringify(entry).
During hydration, client computes the same cache_hash, consumes the matching
SSR script once, and returns that value without an RPC call.
For later interactions (or hydration misses), client calls
POST /_$_ripple_rpc_$_/<function_hash> with build-generated protocol metadata
(version, acceptEncodings), then decodes server-selected encoding/version
without storing a persistent local result cache.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

RFC: Server Function Serialization And Hydration #777

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

RFC: Server Function Serialization And Hydration #777

Uh oh!

Uh oh!

leonidaz Mar 2, 2026 Maintainer

RFC: Server Function Serialization And Hydration

Summary

Motivation

Goals

Non-Goals

Terminology

Detailed Proposal

1. SSR Serialization and Client Hydration for #server Exports

1.1 Compile-time transform

1.2 Script payload format

1.3 Client behavior

1.4 Custom serializer/parser extension points

2. Cache Key and Hash Strategy

2.1 Canonical key input

2.2 Hash algorithm

2.3 Collision handling

3. RPC Transport: Hash-Addressed POST Endpoint

3.1 Transport shape

3.2 RPC policy

3.3 Security and limits

4. #server Block Caching

4.1 Module-level in-memory cache

4.2 Cross-request persistence (optional)

4.3 Invalidation controls

5. Universal Functions: Semantics and Diagnostics

5.1 Problem

5.2 Compiler warnings

5.3 Environment behavior

5.4 Diagnostic scope exclusion

6. Validation Model for #server Function Arguments

6.1 Validation hook

6.2 Third-party schema integration (required)

6.3 Enforcement behavior

6.4 How to enforce coverage across different libraries

7. Error and Serialization Constraints

7.1 Serializable value contract

7.2 Error transport

Compiler and Runtime Implementation Sketch

Compiler

Server runtime

Client runtime

Backward Compatibility and Migration

Alternatives Considered

Open Questions

Rollout Plan

Appendix: Full Concrete Example

A. Source module

B. Server compilation shape with RFC runtime logic

C. Client compilation shape with RFC runtime logic

D. Client runtime hydration + rpc protocol negotiation

E. End-to-end sequence

Replies: 0 comments

leonidaz
Mar 2, 2026
Maintainer

1. SSR Serialization and Client Hydration for `#server` Exports

4. `#server` Block Caching

6. Validation Model for `#server` Function Arguments