Skip to main content

expand_url_template

jmap_base_client

Function expand_url_template 

Source 
pub fn expand_url_template(
    template: &str,
    vars: &[(&str, &str)],
) -> Result<String, ClientError>
Expand description

Expand a RFC 6570 Level-1 URI template by substituting variables.

For each (name, value) pair in vars, replaces {name} in template with the percent-encoded form of value. Encoding follows RFC 3986 unreserved characters (ALPHA / DIGIT / - / . / _ / ~), which pass through unchanged; all other bytes are encoded as %XX with uppercase hex (RFC 3986 §2.1 requires uppercase).

Entries in vars whose name does not appear in the template are silently ignored. A variable that appears in the template but has no entry in vars is an error (ClientError::InvalidSession) because templates come from the server’s Session document — an unexpected variable indicates a server bug.

§RFC 6570 Level-1

Only simple-string expansion is supported. Reserved-expansion ({+var}) and other Level-2+ operators are not supported.

§⚠ Level-2+ templates silently mis-expand (bd:JMAP-6r7c.32)

A server that returns a Level-2 or higher template — e.g. {+blobId} (reserved-expansion), {#var} (fragment-style), or {var*} (list-shaped) — will NOT be detected as malformed. The {+blobId} form parses as a variable name +blobId which is then either replaced verbatim (if a caller happens to pass that exact name in vars) or rejected as an unknown variable. The percent-encoding logic treats every non-unreserved byte as something to escape; Level-2 reserved expansion EXPECTS reserved characters like / and : to pass through unchanged. A server using {+downloadId} to embed a slash-bearing identifier directly would have those slashes percent-encoded by this function and the resulting URL would be rejected server-side.

JMAP servers SHOULD use Level-1 templates only per RFC 8620 §2. If your server uses higher levels, you must expand the template yourself with an RFC-6570-compliant external library and pass the already-expanded URL to methods that accept a plain URL — do not pass a Level-2+ template through this function.

§Usage with subscribe_events

Session::event_source_url is a URI template with variables types, closeafter, and ping. Expand it before calling JmapClient::subscribe_events:

ⓘ
let url = expand_url_template(
    &session.event_source_url,
    &[
        ("types", "Email,Mailbox"),
        ("closeafter", "state"),
        ("ping", "0"),
    ],
)?;
client.subscribe_events(&url, None).await?;