server_less/

lib.rs

//! Server-less - Composable derive macros for Rust
//!
//! Server-less takes an **impl-first** approach: write your Rust methods,
//! and derive macros project them into various protocols (HTTP, CLI, MCP, WebSocket).
//!
//! # Quick Start
//!
//! ```no_run
//! use server_less::prelude::*;
//! use serde::{Deserialize, Serialize};
//!
//! #[derive(Serialize, Deserialize)]
//! struct User { name: String, email: String }
//!
//! #[derive(Debug, ServerlessError)]
//! enum UserError { NotFound }
//!
//! struct UserService;
//!
//! #[mcp]
//! impl UserService {
//!     /// Create a new user
//!     async fn create_user(&self, name: String, email: String) -> Result<User, UserError> {
//!         Ok(User { name, email })
//!     }
//!
//!     /// List all users
//!     async fn list_users(&self, limit: Option<u32>) -> Vec<User> {
//!         let _ = limit;
//!         vec![]
//!     }
//! }
//! ```
//!
//! This generates:
//! - **MCP**: Tools `create_user`, `list_users` (Model Context Protocol)
//!
//! # Available Macros
//!
//! **Blessed presets** (batteries-included, use these to get started):
//!
//! | Macro | Combines | Feature |
//! |-------|----------|---------|
//! | `#[server]` | `#[http]` (with OpenAPI) + `#[serve(http)]` | `http` |
//! | `#[program]` | `#[cli]` + `#[markdown]` | `cli` |
//! | `#[tool]` | `#[mcp]` + `#[jsonschema]` | `mcp` |
//! | `#[rpc]` | `#[jsonrpc]` + `#[openrpc]` + `#[serve(jsonrpc)]` | `jsonrpc` |
//!
//! **À la carte macros** (explicit composition):
//!
//! | Macro | Protocol | Generated Methods |
//! |-------|----------|-------------------|
//! | `#[http]` | HTTP/REST | `http_router()`, `http_openapi_spec()`, `http_openapi_paths()` |
//! | `#[cli]` | Command Line | `cli_command()`, `cli_run()`, `cli_run_with()`, `cli_run_async()`, `cli_run_with_async()` |
//! | `#[mcp]` | MCP | `mcp_tools()`, `mcp_call()`, `mcp_call_async()`, `mcp_method_names()` |
//! | `#[ws]` | WebSocket | `ws_router()`, `ws_handle_message()`, `ws_handle_message_async()`, `ws_methods()` |
//! | `#[jsonrpc]` | JSON-RPC 2.0 | `jsonrpc_router()`, `jsonrpc_methods()`, `jsonrpc_handle_async()` |
//! | `#[graphql]` | GraphQL | async-graphql integration |
//! | `#[grpc]` | gRPC | `.proto` schema generation |
//!
//! **Cross-cutting attributes:**
//!
//! | Macro | Purpose |
//! |-------|---------|
//! | `#[app(...)]` | Attach protocol-neutral metadata (name, description, version, homepage) |
//! | `#[derive(Config)]` | Generate config loading from env vars, TOML files, and defaults |
//! | `#[derive(ServerlessError)]` | Derive `IntoErrorCode` + `Display` + `Error` for error enums |
//! | `#[route(...)]` | Per-method HTTP overrides (method, path, skip, hidden) |
//! | `#[response(...)]` | Per-method response customization |
//! | `#[param(...)]` | Per-parameter metadata (name, default, location, env, help) |
//!
//! # Naming Conventions
//!
//! Method names infer HTTP methods and CLI subcommand structure:
//!
//! | Prefix | HTTP | CLI |
//! |--------|------|-----|
//! | `create_*`, `add_*` | POST | `<cmd> create-*` |
//! | `get_*`, `fetch_*` | GET (single) | `<cmd> get-*` |
//! | `list_*`, `find_*` | GET (collection) | `<cmd> list-*` |
//! | `update_*`, `set_*` | PUT | `<cmd> update-*` |
//! | `delete_*`, `remove_*` | DELETE | `<cmd> delete-*` |
//!
//! # Return Types
//!
//! | Type | HTTP | CLI | MCP/WS |
//! |------|------|-----|--------|
//! | `T` | 200 + JSON | stdout JSON | JSON result |
//! | `Option<T>` | 200 or 404 | stdout or exit 1 | result or null |
//! | `Result<T, E>` | 200 or error | stdout or stderr | result or error |
//! | `()` | 204 | silent | `{"success": true}` |
//! | `impl Stream<Item=T>` | SSE | N/A | N/A |
//!
//! # Async Methods
//!
//! All macros support async methods:
//!
//! ```no_run
//! use server_less::prelude::*;
//!
//! struct MyService;
//!
//! #[mcp]
//! impl MyService {
//!     /// Sync method - works with mcp_call() and mcp_call_async()
//!     pub fn sync_method(&self) -> String {
//!         String::from("hello")
//!     }
//!
//!     /// Async method - use mcp_call_async() for proper await
//!     pub async fn async_method(&self) -> String {
//!         String::from("hello async")
//!     }
//! }
//!
//! #[tokio::main]
//! async fn main() {
//!     let service = MyService;
//!     // Sync call (errors on async methods)
//!     service.mcp_call("sync_method", serde_json::json!({}));
//!     // Async call (awaits async methods properly)
//!     service.mcp_call_async("async_method", serde_json::json!({})).await;
//! }
//! ```
//!
//! # SSE Streaming (HTTP)
//!
//! Return `impl Stream<Item=T>` for Server-Sent Events:
//!
//! ```no_run
//! use server_less::prelude::*;
//! use serde::{Deserialize, Serialize};
//!
//! #[derive(Clone, Serialize, Deserialize)]
//! struct Event { message: String }
//!
//! #[derive(Clone)]
//! struct StreamService;
//!
//! #[http]
//! impl StreamService {
//!     // Note: Rust 2024 requires `+ use<>` to avoid lifetime capture
//!     pub fn stream_events(&self) -> impl futures::Stream<Item = Event> + use<> {
//!         futures::stream::iter(vec![Event { message: String::from("hello") }])
//!     }
//! }
//! ```
//!
//! # Application Metadata
//!
//! `#[app]` attaches protocol-neutral metadata consumed by all protocol macros on the same impl:
//!
//! ```no_run
//! use server_less::prelude::*;
//! use server_less::{app, __app_meta};
//!
//! #[derive(Clone)]
//! struct MyApi;
//!
//! #[app(name = "myapi", description = "My API", version = "1.0.0")]
//! #[server]
//! impl MyApi {
//!     pub fn hello(&self) -> String { String::from("hi") }
//! }
//! ```
//!
//! Preset macros also accept metadata inline:
//!
//! ```no_run
//! use server_less::prelude::*;
//!
//! #[derive(Clone)]
//! struct MyApi;
//!
//! #[server(name = "myapi", description = "My API")]
//! impl MyApi {
//!     pub fn hello(&self) -> String { String::from("hi") }
//! }
//! ```
//!
//! # Config Management
//!
//! `#[derive(Config)]` generates config loading from env vars, TOML files, and defaults:
//!
//! ```no_run
//! use server_less::prelude::*;
//! # #[cfg(feature = "config")]
//! use server_less::{ConfigLoad, ConfigSource};
//!
//! # #[cfg(feature = "config")]
//! #[derive(server_less::Config)]
//! struct AppConfig {
//!     #[param(default = "localhost")]
//!     host: String,
//!     #[param(default = 8080)]
//!     port: u16,
//!     #[param(env = "DATABASE_URL")]
//!     database_url: String,
//! }
//! ```
//!
//! Pass the config type to `#[server]` to add a `config` subcommand and wire it into serve:
//!
//! ```no_run
//! use server_less::prelude::*;
//!
//! #[derive(Clone)]
//! struct MyService;
//!
//! // #[server(config = AppConfig)]
//! #[server]
//! impl MyService {
//!     pub fn hello(&self) -> String { String::from("hi") }
//! }
//! ```
//!
//! # Feature Flags
//!
//! Enable only what you need:
//!
//! ```toml
//! [dependencies]
//! server-less = { version = "0.4", default-features = false, features = ["http", "cli"] }
//! ```
//!
//! Available features:
//! - `mcp` - MCP macro (no extra deps)
//! - `http` - HTTP macro (requires axum)
//! - `cli` - CLI macro (requires clap)
//! - `ws` - WebSocket macro (requires axum, futures)
//! - `jsonrpc` - JSON-RPC 2.0 macro
//! - `graphql` - GraphQL macro (requires async-graphql)
//! - `grpc` - gRPC `.proto` schema generation (no runtime deps)
//! - `capnp` - Cap'n Proto `.capnp` schema generation (no runtime deps)
//! - `thrift` - Apache Thrift `.thrift` IDL generation (no runtime deps)
//! - `connect` - Connect RPC schema generation (no runtime deps)
//! - `smithy` - AWS Smithy `.smithy` model generation (no runtime deps)
//! - `openapi` - Standalone OpenAPI spec generation (no axum required)
//! - `openrpc` - OpenRPC spec generation (no runtime deps)
//! - `asyncapi` - AsyncAPI spec generation (no runtime deps)
//! - `jsonschema` - JSON Schema generation (no runtime deps)
//! - `markdown` - Markdown API docs generation (no runtime deps)
//! - `config` - `#[derive(Config)]` for config loading (requires toml)
//! - `full` - All features (default)

// Re-export macros (feature-gated)
#[cfg(feature = "mcp")]
pub use server_less_macros::mcp;

#[cfg(feature = "http")]
pub use server_less_macros::http;

#[cfg(any(feature = "http", feature = "openapi"))]
pub use server_less_macros::openapi;

#[cfg(feature = "http")]
pub use server_less_macros::route;

#[cfg(feature = "http")]
pub use server_less_macros::response;

#[cfg(any(feature = "http", feature = "cli", feature = "mcp"))]
pub use server_less_macros::param;

#[cfg(feature = "http")]
pub use server_less_macros::serve;

#[cfg(feature = "cli")]
pub use server_less_macros::cli;

#[cfg(feature = "cli")]
pub use server_less_core::CliSubcommand;

#[cfg(feature = "cli")]
pub use server_less_core::cli_format_output;

#[cfg(feature = "cli")]
pub use server_less_core::{CliManualNode, cli_manual_to_json, cli_manual_to_text};

#[cfg(feature = "mcp")]
pub use server_less_core::McpNamespace;

#[cfg(feature = "jsonrpc")]
pub use server_less_core::JsonRpcMount;

#[cfg(feature = "ws")]
pub use server_less_core::WsMount;

#[cfg(feature = "http")]
pub use server_less_core::HttpMount;

#[cfg(feature = "ws")]
pub use server_less_macros::ws;

#[cfg(feature = "jsonrpc")]
pub use server_less_macros::jsonrpc;

#[cfg(feature = "openrpc")]
pub use server_less_macros::openrpc;

#[cfg(feature = "graphql")]
pub use server_less_macros::graphql;
#[cfg(feature = "graphql")]
pub use server_less_macros::graphql_enum;
#[cfg(feature = "graphql")]
pub use server_less_macros::graphql_input;

#[cfg(feature = "grpc")]
pub use server_less_macros::grpc;

#[cfg(feature = "capnp")]
pub use server_less_macros::capnp;

#[cfg(feature = "thrift")]
pub use server_less_macros::thrift;

#[cfg(feature = "connect")]
pub use server_less_macros::connect;

#[cfg(feature = "smithy")]
pub use server_less_macros::smithy;

#[cfg(feature = "markdown")]
pub use server_less_macros::markdown;

#[cfg(feature = "jsonschema")]
pub use server_less_macros::jsonschema;

#[cfg(feature = "asyncapi")]
pub use server_less_macros::asyncapi;

// Blessed presets
#[cfg(feature = "http")]
pub use server_less_macros::server;

#[cfg(feature = "jsonrpc")]
pub use server_less_macros::rpc;

#[cfg(feature = "mcp")]
pub use server_less_macros::tool;

#[cfg(feature = "cli")]
pub use server_less_macros::program;

// Error derive macro (always available - no deps, commonly needed)
pub use server_less_macros::ServerlessError;

// Application metadata attribute (always available)
pub use server_less_macros::app;
#[doc(hidden)]
pub use server_less_macros::__app_meta;

// Standalone health-check derive
#[cfg(feature = "health")]
pub use server_less_macros::HealthCheck;

// Config derive macro
#[cfg(feature = "config")]
pub use server_less_macros::Config;
#[cfg(feature = "config")]
pub use server_less_core::config::{ConfigLoad, ConfigError, ConfigFieldMeta, ConfigSource};

// Re-export deps for generated code — users shouldn't need to add these directly
#[cfg(feature = "cli")]
#[doc(hidden)]
pub use clap;

// Shell completions / man page generators for the #[cli] projection
#[cfg(feature = "completions")]
#[doc(hidden)]
pub use clap_complete;
#[cfg(feature = "completions")]
#[doc(hidden)]
pub use clap_mangen;

#[cfg(any(feature = "cli", feature = "http"))]
#[doc(hidden)]
pub use tokio;

#[cfg(any(feature = "http", feature = "ws", feature = "jsonrpc", feature = "graphql"))]
#[doc(hidden)]
pub use axum;

// Re-export futures for generated WebSocket code
#[cfg(feature = "ws")]
#[doc(hidden)]
pub use futures;

// Re-export async-graphql for generated GraphQL code
#[cfg(feature = "graphql")]
#[doc(hidden)]
pub use async_graphql;
#[cfg(feature = "graphql")]
#[doc(hidden)]
pub use async_graphql_axum;

// Re-export core types
pub use server_less_core::*;

// Re-export OpenAPI composition utilities (available when any protocol that generates OpenAPI is enabled)
#[cfg(feature = "server-less-openapi")]
pub use server_less_openapi::{
    OpenApiBuilder, OpenApiError, OpenApiOperation, OpenApiParameter, OpenApiPath, OpenApiSchema,
};

// Re-export serde for generated code
pub use serde;
pub use serde_json;

/// Prelude for convenient imports
pub mod prelude {
    // Runtime protocols
    #[cfg(feature = "cli")]
    pub use super::CliSubcommand;
    #[cfg(feature = "http")]
    pub use super::HttpMount;
    #[cfg(feature = "jsonrpc")]
    pub use super::JsonRpcMount;
    #[cfg(feature = "mcp")]
    pub use super::McpNamespace;
    #[cfg(feature = "ws")]
    pub use super::WsMount;
    #[cfg(feature = "cli")]
    pub use super::cli;
    #[cfg(feature = "graphql")]
    pub use super::graphql;
    #[cfg(feature = "graphql")]
    pub use super::graphql_enum;
    #[cfg(feature = "graphql")]
    pub use super::graphql_input;
    #[cfg(feature = "http")]
    pub use super::http;
    #[cfg(feature = "jsonrpc")]
    pub use super::jsonrpc;
    #[cfg(feature = "mcp")]
    pub use super::mcp;
    #[cfg(any(feature = "http", feature = "openapi"))]
    pub use super::openapi;
    #[cfg(feature = "http")]
    pub use super::response;
    #[cfg(feature = "http")]
    pub use super::route;
    #[cfg(feature = "http")]
    pub use super::serve;
    #[cfg(feature = "ws")]
    pub use super::ws;

    // Schema generators
    #[cfg(feature = "capnp")]
    pub use super::capnp;
    #[cfg(feature = "connect")]
    pub use super::connect;
    #[cfg(feature = "grpc")]
    pub use super::grpc;
    #[cfg(feature = "smithy")]
    pub use super::smithy;
    #[cfg(feature = "thrift")]
    pub use super::thrift;

    // Specification generators
    #[cfg(feature = "asyncapi")]
    pub use super::asyncapi;
    #[cfg(feature = "jsonschema")]
    pub use super::jsonschema;
    #[cfg(feature = "openrpc")]
    pub use super::openrpc;

    // Documentation generators
    #[cfg(feature = "markdown")]
    pub use super::markdown;

    // Blessed presets
    #[cfg(feature = "cli")]
    pub use super::program;
    #[cfg(feature = "jsonrpc")]
    pub use super::rpc;
    #[cfg(feature = "http")]
    pub use super::server;
    #[cfg(feature = "mcp")]
    pub use super::tool;

    // Always available
    pub use super::{Context, ErrorCode, ErrorResponse, IntoErrorCode, ServerlessError};

    // OpenAPI composition (available when any protocol that generates OpenAPI is enabled)
    #[cfg(feature = "server-less-openapi")]
    pub use super::OpenApiBuilder;
    pub use serde::{Deserialize, Serialize};

    // WebSocket sender (when ws feature enabled)
    #[cfg(feature = "ws")]
    pub use super::WsSender;
}