url-utils

Shared, wasm-compatible foundation for describing HTTP models and building requests, plus the low-level URL helpers it is built on.

Describe an HTTP model once with the derive macros: on the client the same model builds an outgoing request; on the server (my-http-server, which depends on url-utils) its own macros generate controllers and request parsing from the same markup. url-utils has no hyper/tokio/server dependencies, so models compile to wasm32-unknown-unknown.

Workspace

• url-utils — the library.
• http-request-schema-macros — proc-macro crate, re-exported as url_utils::macros (use it from there, never directly).
• tests — integration tests for the macros.

Main types

Describing a model (url_utils::macros)

macro	what it's for
MyHttpInput	derive on a request model: emits the schema + the client request builder
MyHttpObjectStructure / MyHttpInputObjectStructure	describe a nested object used in a body/response
MyHttpStringEnum / MyHttpIntegerEnum	use an enum as a parameter value
#[http_input_field]	a custom String-wrapper field type

Field markup: #[http_query], #[http_path], #[http_header], #[http_form_data], #[http_body], #[http_body_raw] — each with name, description, validator, to_lowercase, to_uppercase, trim, default, print_request_to_console.

Building a request (url_utils::schema::client)

type	what it's for
THttpRequestBuilder	generated by MyHttpInput: fill_url / fill_headers / get_body turn a model into request parts
HeaderBuilder	sink a transport (e.g. fl-url) implements to receive headers
HttpRequestBuildError	returned when a field validator rejects the outgoing value

Bodies, URL, readers

type	what it's for
url_utils::UrlBuilder	build / inspect a URL (path segments + query, TCP or unix-socket)
url_utils::body::HttpRequestBody	an outgoing body: Json / UrlEncoded / FormData / Raw / Empty
url_utils::body::{FormDataBody, UrlEncodedBody}	build multipart/form-data / x-www-form-urlencoded bodies
url_utils::url_encoded_data_reader::UrlEncodedDataReader	read x-www-form-urlencoded (query strings / bodies)
url_utils::form_data_reader::FormDataReader	read multipart/form-data
url_utils::url_encoder / url_utils::url_decoder	percent encode / decode

Schema (url_utils::schema)

data_types (DataTypeProvider, HttpDataType, …), in_parameters (HttpInputParameter, …) and out_results describe a model's shape — used for OpenAPI/Swagger on the server and for parameter metadata. Generated by the derives; you rarely touch these directly.

Examples

Describe a model

use url_utils::macros::*;
use serde::Serialize;

#[derive(Serialize, MyHttpInput)]
pub struct CreateUser {
    #[http_path(name = "orgId", description = "Organisation id")]
    pub org_id: String,
    #[http_query(name = "notify", description = "Send a welcome email")]
    pub notify: bool,
    #[http_header(name = "X-Api-Key", description = "API key")]
    pub api_key: String,
    #[http_body(name = "name", description = "User name", trim)]
    pub name: String,
}

Build a request from it

use url_utils::UrlBuilder;
use url_utils::schema::client::THttpRequestBuilder;

let mut url = UrlBuilder::new("https://api.example.com");
model.fill_url(&mut url)?;                 // "https://api.example.com/42?notify=true"
model.fill_headers(&mut headers)?;         // your transport's HeaderBuilder
let body = model.get_body()?;              // HttpRequestBody::Json(...)

A thin adapter (fl-url on native, fetch/gloo on wasm) turns UrlBuilder + headers + HttpRequestBody into a real request.

Read a query string

use url_utils::url_encoded_data_reader::UrlEncodedDataReader;

let reader = UrlEncodedDataReader::new("name=hello+world&id=5")?;
let name = reader.get_required("name")?.as_string()?; // "hello world"

wasm

url-utils is wasm-compatible (wasm32-unknown-unknown): no hyper/tokio, no server-only code.

Tests

cargo test