siderite_macros/

lib.rs

//! Procedural macros for siderite.
//!
//! These macros are re-exported by the `siderite` facade crate; generated code
//! only refers to `::siderite::...` paths, so depend on `siderite`, not on this
//! crate directly.
//!
//! * `#[get("/path", ...)]`, `#[post(..)]`, `#[put(..)]`, `#[patch(..)]`,
//!   `#[delete(..)]`, `#[head(..)]`, `#[options(..)]`, `#[ws(..)]`: attach a
//!   route (and its OpenAPI metadata) to an `async fn` handler.
//! * `routes![a, module::b]`: collect the routes generated by those attributes.
//! * `#[derive(Schema)]`: JSON Schema / OpenAPI schema generation compatible
//!   with the common `serde` attributes, plus the matching `Dump`.
//! * `#[derive(Validate)]`: request validation (coercion, constraints,
//!   aliases, string transforms) generated from the same attributes.
//! * `#[derive(Model)]`: ORM model metadata, typed field handles, the `Model`
//!   implementation and relation accessors.
//! * `#[model_hooks]`: field/model validators, computed fields and
//!   serializers on an inherent `impl` block.
#![forbid(unsafe_code)]

mod attrs;
mod diag;
mod docs;
mod generics;
mod hooks;
mod meta;
mod model;
mod probe;
mod receiver;
mod route;
mod routes;
mod schema;
mod validate;

use proc_macro::TokenStream;

macro_rules! route_macros {
    ($($(#[$doc:meta])* $name:ident => $method:ident),+ $(,)?) => {$(
        $(#[$doc])*
        #[proc_macro_attribute]
        pub fn $name(args: TokenStream, item: TokenStream) -> TokenStream {
            route::expand(route::Method::$method, args.into(), item.into()).into()
        }
    )+};
}

route_macros! {
    /// Route `GET` requests to the annotated `async fn`.
    ///
    /// Syntax: `#[get("/path/{param}", status = 200, tag = "t", tags("a", "b"),
    /// summary = "..", description = "..", operation_id = "..",
    /// response_model = Type, deprecated, hidden)]`.
    get => Get,
    /// Route `POST` requests to the annotated `async fn`. See [`macro@get`].
    post => Post,
    /// Route `PUT` requests to the annotated `async fn`. See [`macro@get`].
    put => Put,
    /// Route `PATCH` requests to the annotated `async fn`. See [`macro@get`].
    patch => Patch,
    /// Route `DELETE` requests to the annotated `async fn`. See [`macro@get`].
    delete => Delete,
    /// Route `HEAD` requests to the annotated `async fn`. See [`macro@get`].
    head => Head,
    /// Route `OPTIONS` requests to the annotated `async fn`. See [`macro@get`].
    options => Options,
    /// Route a WebSocket upgrade (a `GET` request) to the annotated `async fn`.
    /// See [`macro@get`].
    ws => Ws,
}

/// Collect the routes of handlers annotated with the route attributes.
///
/// `routes![create_user, users::list]` expands to
/// `::std::vec![__siderite_route_create_user(), users::__siderite_route_list()]`
/// (only the last path segment is rewritten), suitable for `App::routes`.
#[proc_macro]
pub fn routes(input: TokenStream) -> TokenStream {
    routes::expand(input.into()).into()
}

/// Derive `siderite::validation::Schema` (JSON Schema / OpenAPI 3.1) and the
/// matching `siderite::validation::Dump`.
///
/// Helper attributes: `#[schema(name = "..", inline, no_dump)]`,
/// `#[field(...)]`, `#[model_config(...)]` and the compatible subset of
/// `#[serde(...)]`. See [`macro@Validate`] for the shared attributes.
///
/// `Dump` is implemented for every derived type, but the impl only applies
/// when the type is `Serialize` (input-only types are unaffected). Add
/// `#[schema(no_dump)]` to opt out.
#[proc_macro_derive(Schema, attributes(schema, field, serde, model_config))]
pub fn derive_schema(input: TokenStream) -> TokenStream {
    let input = syn::parse_macro_input!(input as syn::DeriveInput);
    match schema::derive(&input) {
        Ok(tokens) => tokens.into(),
        Err(err) => err.into_compile_error().into(),
    }
}

/// Derive `siderite::validation::Validate`.
///
/// Serde stays the single source of truth for wire names, defaults and
/// skipping; `derive(Schema)`, `derive(Validate)` and the generated `Dump`
/// share one attribute model, so key names and required-ness cannot drift.
///
/// # `#[model_config(...)]`
/// `strict`, `extra = "forbid" | "ignore" | "allow"`, `str_strip_whitespace`,
/// `str_to_lower`, `str_to_upper`, `populate_by_name` (the Rust field name
/// is accepted as an input key too) and `hooks` (see below). Flags accept
/// `flag` and `flag = true`. Serde's `deny_unknown_fields` implies
/// `extra = "forbid"` unless `extra` is given. As with `deny_unknown_fields`,
/// the key of a `#[serde(skip_deserializing)]` (or `skip`) field is not an
/// input, so under `extra = "forbid"` sending it is `extra_forbidden`.
///
/// # `#[field(...)]`
/// Constraints: `min_length`, `max_length`, `pattern` (or `regex`, checked at
/// compile time), `email`, `gt`, `ge`, `lt`, `le`, `multiple_of` (numeric
/// literals). Naming: `alias` (must equal the serde key; use
/// `#[serde(rename)]` to rename), `validation_alias` (extra accepted input
/// key), `serialization_alias` (must equal the serde key: there is one schema
/// per type, unlike Pydantic). Defaults: `default = <expr>` /
/// `default_factory = path` document the default and drive
/// `exclude_defaults`; the field must *also* have a serde default
/// (`#[serde(default)]`, `#[serde(default = "path")]`, or a container
/// default), which stays the source of truth for deserialization.
/// Annotations: `title`, `description`, `examples(..)`, `url`,
/// `max_digits`/`decimal_places` (documented as `x-` schema extensions,
/// not enforced). Behaviour: `exclude` (skipped by `Dump`, input still
/// accepted), `strict` (strict coercion for this field only) and
/// `validator = path` (repeatable reusable after-validator
/// `fn(&FieldTy) -> Result<(), FieldError>`). Unknown keys are compile
/// errors listing the valid ones.
///
/// # Supported shapes
/// * Structs with named fields: full validation.
/// * Newtype structs delegate to the inner type.
/// * Enums with only unit variants (default representation) check that the
///   input is one of the serde names (error code `enum`).
/// * Other enums and tuple/unit structs implement `Validate` without
///   validating anything themselves.
///
/// # Hooks and generics
/// Hooks defined with [`macro@model_hooks`] are found automatically for
/// concrete types. For **generic** types the derive cannot detect a
/// `ModelHooks` impl, so it emits no hook calls unless the type says
/// `#[model_config(hooks)]`, which calls `<Self as ModelHooks>` directly (an
/// impl is then required, even if empty). Type parameters get a `Validate`
/// bound.
#[proc_macro_derive(Validate, attributes(schema, field, serde, model_config))]
pub fn derive_validate(input: TokenStream) -> TokenStream {
    let input = syn::parse_macro_input!(input as syn::DeriveInput);
    match validate::derive(&input) {
        Ok(tokens) => tokens.into(),
        Err(err) => err.into_compile_error().into(),
    }
}

/// Turn an inherent `impl` block into a `ModelHooks` implementation.
///
/// Helper attributes on the methods (removed from the emitted impl):
///
/// * `#[field_validator("a", "b", mode = "after")]`:
///   `fn(value: &FieldTy) -> Result<(), FieldError>`, run on the typed value
///   at the field's input key; `&String` coerces to `&str`. With
///   `mode = "before"`: `fn(value: &mut serde_json::Value)`, run on the raw
///   slot before the field is coerced. Field names are resolved as real
///   fields, so a typo is a compile error. Requires `derive(Validate)`.
/// * `#[model_validator(mode = "after")]`: `fn(&self) -> Result<(), FieldError>`;
///   `mode = "before"`: `fn(input: &mut Value) -> Result<(), FieldError>`.
///   Errors are located at the model unless the `FieldError` has a location.
/// * `#[computed_field]` / `#[computed_field(alias = "name")]`:
///   `fn(&self) -> T` with `T: Dump + Schema` (an explicit type, not
///   `impl Trait`). Included by `Dump` (respecting include/exclude) and
///   documented as a `readOnly` property.
/// * `#[field_serializer("field")]`: `fn(value: &FieldTy) -> V`, `V:
///   Serialize` (`serde_json::Value` included), replaces the field's dumped
///   value.
/// * `#[model_serializer]`: `fn(&self, value: Value) -> Value`, applied to
///   the finished object.
///
/// Hooks run in declaration order. Generic impls are supported (the
/// generics and where clause are copied); the model then needs
/// `#[model_config(hooks)]` and the impl's bounds must be satisfiable where
/// the model is used.
#[proc_macro_attribute]
pub fn model_hooks(args: TokenStream, item: TokenStream) -> TokenStream {
    hooks::expand(args.into(), item.into()).into()
}

/// Derive `siderite::orm::Model`: static column metadata, one typed
/// `Field<Self, T>` constant per field (`User::name`), `to_values` /
/// `from_row`, and the relation accessors.
///
/// One struct can derive `Model, Validate, Schema, Serialize, Deserialize`
/// together: the ORM keys of `#[field(...)]` are ignored by the other derives,
/// and `Model` ignores their validation keys (except `max_length`,
/// `max_digits` and `decimal_places`, which become column metadata).
///
/// # `#[model(...)]` on the struct
/// * `table = "users"`: table name. Default: the snake_case of the type
///   name (`BlogPost` becomes `blog_post`); there is no app prefix or
///   pluralisation.
/// * `ordering = ["name", "-created_at"]`: default ordering; a leading `-`
///   is descending. Entries are field names (or column names).
/// * `indexes(idx_name(columns = ["a", "b"], unique))`: named indexes.
/// * `unique_together(["a", "b"], ["c", "d"])`: unique constraints, named
///   `{table}_{columns}_uniq`.
/// * `checks(age_positive = "age >= 0")`: named `CHECK` constraints. The SQL
///   is written by the model author, never built from user input.
/// * `managed = false`: migrations leave the table alone.
/// * `many_to_many(tags(Tag, through_table = "post_tags", source_column = "..",
///   target_column = "..", related_name = "posts"))`: many-to-many relations
///   (not struct fields). Defaults: `through_table` is `{table}_{name}`,
///   `source_column` is `{snake(Model)}_id` and `target_column` is
///   `{snake(Target)}_id` (set both explicitly for a self-referential
///   relation). `through = Model` uses an explicit through model: its table
///   is the join table (`through_table` must then be omitted).
///
/// Indexes, unique groups and ordering are checked at compile time: unknown
/// fields are errors.
///
/// # `#[field(...)]` ORM keys
/// * `primary_key`: exactly one field must have it. Without a declared key
///   the derive suggests `#[field(primary_key, auto)] id: i64`.
/// * `auto`: database-generated integer primary key (`i16`, `i32`, `i64`).
///   The model is unsaved while the key equals `Default::default()`; a
///   primary key without `auto` is never "unsaved".
/// * `unique`, `index`: constraint and single-column index.
/// * `column = "name"`: column name (default: the field name, or
///   `{field}_id` for relations).
/// * `db_default = <int | bool | "text">`: server-side default.
/// * `auto_now_add` / `auto_now`: `DbDefault::Now` at insert / refresh on
///   every save (the queryset layer fills the value; the derive only emits
///   metadata).
/// * `on_delete = "cascade" | "protect" | "set_null" | "set_default" |
///   "do_nothing"` and `related_name = ".."`: relation fields only.
///   `set_null` requires `Option<ForeignKey<..>>`.
/// * `skip`: not a column; the field is `Default::default()` when loaded.
/// * `max_length`, `max_digits`, `decimal_places`: column metadata.
///
/// # Relations
/// Fields typed `ForeignKey<T>`, `OneToOne<T>` or `Option<..>` of those are
/// relations; a `OneToOne` is unique. The field's constant is a
/// `Field<Self, ForeignKey<T>>` over the `{field}_id` column, and an async
/// `fetch_{field}(&self, &Db)` loads the target (the name differs from the
/// field's because an associated constant and a method cannot share a name).
/// With `related_name`, the target type gets a reverse accessor
/// (`author.books(&db)` returning a `QuerySet`, or an async `Option` lookup
/// for a `OneToOne`); the target model must be defined in the same crate.
/// Each many-to-many gets `post.tags(&db)` returning a
/// `ManyToManyManager`, and with `related_name` a reverse
/// `tag.posts(&db)` queryset.
///
/// Generated accessors can clash with methods you write yourself; the
/// compiler reports the duplicate.
///
/// Generic types are not supported.
#[proc_macro_derive(Model, attributes(model, field, serde))]
pub fn derive_model(input: TokenStream) -> TokenStream {
    let input = syn::parse_macro_input!(input as syn::DeriveInput);
    match model::derive(&input) {
        Ok(tokens) => tokens.into(),
        Err(err) => err.into_compile_error().into(),
    }
}

/// Turn an `async fn` into an ORM signal receiver:
/// `#[receiver(post_save, model = User)]`.
///
/// Generates `fn <name>_receiver() -> ::siderite::orm::signals::Receiver`;
/// register it explicitly with `Signals::connect`. See the ORM signals
/// documentation for ordering and failure semantics.
#[proc_macro_attribute]
pub fn receiver(args: TokenStream, item: TokenStream) -> TokenStream {
    receiver::expand(args.into(), item.into()).into()
}