Skip to main content

sololc_webhook_sdk/
lib.rs

1//! # Sololc Webhook SDK
2//!
3//! Provides a high-performance, modern, and ergonomic WASI-HTTP Webhook SDK
4//! optimized for the Sololc Runtime.
5//!
6//! This crate simplifies the development of Webhook microservices by abstracting
7//! raw WebAssembly System Interface (WASI) HTTP components into a routing style
8//! reminiscent of mainstream Rust web frameworks (such as Axum or Actix-web).
9
10wit_bindgen::generate!({
11    path: "wit",
12    world: "webhook-proxy",
13    generate_all,
14});
15
16mod http_types;
17
18/// Represents the primary entrypoint contract exported to the host gateway.
19///
20/// Under the hood, this handles the low-level WASIp2 `wasi:http/incoming-handler`
21/// interface. It is driven asynchronously by the host executor.
22///
23/// See also [`wasi::http::types`] for the underlying raw assets.
24pub use exports::wasi::http::incoming_handler::Guest;
25
26
27/// Exposes the official WASI-HTTP types used for lower-level requests and responses.
28///
29/// Contains critical raw assets such as [`IncomingRequest`], [`OutgoingResponse`],
30/// [`ResponseOutparam`], and [`Fields`]. For a more ergonomic experience, use the SDK's
31/// high-level wrapper types [`Request`] and [`Response`] instead.
32pub use self::wasi::http::types::{Fields, IncomingRequest, OutgoingResponse, ResponseOutparam};
33
34/// Exposes the ergonomic high-level wrapper types.
35///
36/// Re-exports [`Request`] and [`Response`] which abstract raw incoming streams and
37/// field structures into standard, intuitive web structures.
38pub use self::http_types::{Request, Response};
39
40/// Routes an incoming HTTP `GET` request to the annotated handler function.
41///
42/// Acts as the entrypoint for retrieving read-only resources within your plugin.
43///
44/// # Examples
45///
46/// ```rust
47/// use sololc_webhook_sdk::{get, Request, Response};
48///
49/// #[get("/api/v1/auth")]
50/// async fn check_auth(req: Request) -> Response {
51///     Response::json(200, r#"{"status": "approved"}"#)
52/// }
53/// ```
54pub use sololc_webhook_macros::get;
55
56/// Routes an incoming HTTP `POST` request to the annotated handler function.
57///
58/// Handles data creation, event synchronizations, or heavy payloads sent by Webhook triggers.
59///
60/// # Examples
61///
62/// ```rust
63/// use sololc_webhook_sdk::{post, Request, Response};
64///
65/// #[post("/api/v1/telemetry")]
66/// async fn record_metrics(req: Request) -> Response {
67///     Response::json(201, r#"{"status": "recorded"}"#)
68/// }
69/// ```
70pub use sololc_webhook_macros::post;
71
72/// Routes an incoming HTTP `PUT` request to the annotated handler function.
73///
74/// Replaces or updates an existing entity completely with the provided payload.
75pub use sololc_webhook_macros::put;
76
77/// Routes an incoming HTTP `DELETE` request to the annotated handler function.
78///
79/// Removes or revokes resources associated with the matching routing path.
80pub use sololc_webhook_macros::delete;
81
82/// Routes an incoming HTTP `PATCH` request to the annotated handler function.
83///
84/// Applies partial modifications or fractional updates to a specific resource.
85pub use sololc_webhook_macros::patch;
86
87/// Routes an incoming HTTP `HEAD` request to the annotated handler function.
88///
89/// Retrieves only the headers of a resource, identical to a `GET` request but without the response body.
90pub use sololc_webhook_macros::head;
91
92/// Routes an incoming HTTP `OPTIONS` request to the annotated handler function.
93///
94/// Describes the communication options and allowed methods for the target resource.
95pub use sololc_webhook_macros::options;
96
97// --- 1. Logging client module ---
98#[cfg(feature = "logging")]
99pub mod logging;
100
101/// Initializes the global WASIp2 system logger and binds it to the `log` ecosystem.
102///
103/// Returns a [`Result<(), log::SetLoggerError>`][log::SetLoggerError] indicating
104/// whether the active global logger was bound successfully.
105#[cfg(feature = "logging")]
106pub use logging::init as init_logger;
107
108// --- 2. Key-value storage module ---
109#[cfg(feature = "kv")]
110pub mod kv;
111
112/// Represents a safe, high-level abstraction over the WASIp2 `wasi:keyvalue` system.
113///
114/// Leverages the state-bound APIs provided by the Sololc host executor to persist
115/// and fetch arbitrary byte-buffers synchronously within standard asynchronous routines.
116#[cfg(feature = "kv")]
117pub use kv::KvStore;
118
119// --- 3. Asynchronous HTTP client module ---
120#[cfg(feature = "http-client")]
121pub mod http_client;
122
123/// Dispatches outgoing HTTP requests utilizing the WASIp2 `wasi:http/outgoing-handler`.
124///
125/// Coordinates connection pools and underlying network transports securely via the sandbox gateway.
126#[cfg(feature = "http-client")]
127pub use crate::http_client::client::HttpClient;