r402_http/server/
layer.rs

1//! Axum middleware for enforcing [x402](https://www.x402.org) payments on protected routes.
2//!
3//! This middleware validates incoming payment headers using a configured x402 facilitator,
4//! verifies the payment, executes the request, and settles valid payments after successful
5//! execution. If the handler returns an error (4xx/5xx), settlement is skipped.
6//!
7//! Returns a `402 Payment Required` response if the request lacks a valid payment.
8//!
9//! ## Configuration Notes
10//!
11//! - **[`X402Middleware::with_price_tag`]** sets the assets and amounts accepted for payment (static pricing).
12//! - **[`X402Middleware::with_dynamic_price`]** sets a callback for dynamic pricing based on request context.
13//! - **[`X402Middleware::with_base_url`]** sets the base URL for computing full resource URLs.
14//!   If not set, defaults to `http://localhost/` (avoid in production).
15//! - **[`X402LayerBuilder::with_description`]** is optional but helps the payer understand what is being paid for.
16//! - **[`X402LayerBuilder::with_mime_type`]** sets the MIME type of the protected resource (default: `application/json`).
17//! - **[`X402LayerBuilder::with_resource`]** explicitly sets the full URI of the protected resource.
18//!
19
20use std::convert::Infallible;
21use std::future::Future;
22use std::pin::Pin;
23use std::sync::Arc;
24use std::task::{Context, Poll};
25use std::time::Duration;
26
27use axum_core::extract::Request;
28use axum_core::response::Response;
29use http::{HeaderMap, Uri};
30use r402::facilitator::Facilitator;
31use r402::proto::v2;
32use tower::util::BoxCloneSyncService;
33use tower::{Layer, Service};
34use url::Url;
35
36use super::facilitator::FacilitatorClient;
37use super::paygate::{Paygate, ResourceInfoBuilder};
38use super::pricing::{DynamicPriceTags, PriceTagSource, StaticPriceTags};
39
40/// The main X402 middleware instance for enforcing x402 payments on routes.
41///
42/// Create a single instance per application and use it to build payment layers
43/// for protected routes.
44pub struct X402Middleware<F> {
45    facilitator: F,
46    base_url: Option<Url>,
47}
48
49impl<F: Clone> Clone for X402Middleware<F> {
50    fn clone(&self) -> Self {
51        Self {
52            facilitator: self.facilitator.clone(),
53            base_url: self.base_url.clone(),
54        }
55    }
56}
57
58impl<F: std::fmt::Debug> std::fmt::Debug for X402Middleware<F> {
59    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
60        f.debug_struct("X402Middleware")
61            .field("facilitator", &self.facilitator)
62            .field("base_url", &self.base_url)
63            .finish()
64    }
65}
66
67impl<F> X402Middleware<F> {
68    /// Returns a reference to the underlying facilitator.
69    pub const fn facilitator(&self) -> &F {
70        &self.facilitator
71    }
72}
73
74impl X402Middleware<Arc<FacilitatorClient>> {
75    /// Creates a new middleware instance with a default facilitator URL.
76    ///
77    /// # Panics
78    ///
79    /// Panics if the facilitator URL is invalid.
80    #[must_use]
81    pub fn new(url: &str) -> Self {
82        let facilitator = FacilitatorClient::try_from(url).expect("Invalid facilitator URL");
83        Self {
84            facilitator: Arc::new(facilitator),
85            base_url: None,
86        }
87    }
88
89    /// Creates a new middleware instance with a facilitator URL.
90    ///
91    /// # Errors
92    ///
93    /// Returns an error if the URL is invalid.
94    pub fn try_new(url: &str) -> Result<Self, Box<dyn std::error::Error>> {
95        let facilitator = FacilitatorClient::try_from(url)?;
96        Ok(Self {
97            facilitator: Arc::new(facilitator),
98            base_url: None,
99        })
100    }
101
102    /// Returns the configured facilitator URL.
103    #[must_use]
104    pub fn facilitator_url(&self) -> &Url {
105        self.facilitator.base_url()
106    }
107
108    /// Sets the TTL for caching the facilitator's supported response.
109    ///
110    /// Default is 10 minutes. Use [`FacilitatorClient::without_supported_cache()`]
111    /// to disable caching entirely.
112    #[must_use]
113    pub fn with_supported_cache_ttl(&self, ttl: Duration) -> Self {
114        let inner = Arc::unwrap_or_clone(Arc::clone(&self.facilitator));
115        let facilitator = Arc::new(inner.with_supported_cache_ttl(ttl));
116        Self {
117            facilitator,
118            base_url: self.base_url.clone(),
119        }
120    }
121}
122
123impl TryFrom<&str> for X402Middleware<Arc<FacilitatorClient>> {
124    type Error = Box<dyn std::error::Error>;
125
126    fn try_from(value: &str) -> Result<Self, Self::Error> {
127        Self::try_new(value)
128    }
129}
130
131impl TryFrom<String> for X402Middleware<Arc<FacilitatorClient>> {
132    type Error = Box<dyn std::error::Error>;
133
134    fn try_from(value: String) -> Result<Self, Self::Error> {
135        Self::try_new(&value)
136    }
137}
138
139impl<F> X402Middleware<F>
140where
141    F: Clone,
142{
143    /// Sets the base URL used to construct resource URLs dynamically.
144    ///
145    /// If [`X402LayerBuilder::with_resource`] is not called, this base URL is combined with
146    /// each request's path/query to compute the resource. If not set, defaults to `http://localhost/`.
147    ///
148    /// In production, prefer calling `with_resource` or setting a precise `base_url`.
149    #[must_use]
150    pub fn with_base_url(&self, base_url: Url) -> Self {
151        let mut this = self.clone();
152        this.base_url = Some(base_url);
153        this
154    }
155}
156
157impl<TFacilitator> X402Middleware<TFacilitator>
158where
159    TFacilitator: Clone,
160{
161    /// Sets the price tag for the protected route.
162    ///
163    /// Creates a layer builder that can be further configured with additional
164    /// price tags and resource information.
165    #[must_use]
166    pub fn with_price_tag(
167        &self,
168        price_tag: v2::PriceTag,
169    ) -> X402LayerBuilder<StaticPriceTags, TFacilitator> {
170        X402LayerBuilder {
171            facilitator: self.facilitator.clone(),
172            price_source: StaticPriceTags::new(vec![price_tag]),
173            base_url: self.base_url.clone().map(Arc::new),
174            resource: Arc::new(ResourceInfoBuilder::default()),
175        }
176    }
177
178    /// Sets a dynamic price source for the protected route.
179    ///
180    /// The `callback` receives request headers, URI, and base URL, and returns
181    /// a vector of V2 price tags.
182    #[must_use]
183    pub fn with_dynamic_price<F, Fut>(
184        &self,
185        callback: F,
186    ) -> X402LayerBuilder<DynamicPriceTags, TFacilitator>
187    where
188        F: Fn(&HeaderMap, &Uri, Option<&Url>) -> Fut + Send + Sync + 'static,
189        Fut: Future<Output = Vec<v2::PriceTag>> + Send + 'static,
190    {
191        X402LayerBuilder {
192            facilitator: self.facilitator.clone(),
193            price_source: DynamicPriceTags::new(callback),
194            base_url: self.base_url.clone().map(Arc::new),
195            resource: Arc::new(ResourceInfoBuilder::default()),
196        }
197    }
198}
199
200/// Builder for configuring the X402 middleware layer.
201///
202/// Generic over `TSource` which implements [`PriceTagSource`] to support
203/// both static and dynamic pricing strategies.
204#[derive(Clone)]
205#[allow(missing_debug_implementations)] // generic types may not implement Debug
206pub struct X402LayerBuilder<TSource, TFacilitator> {
207    facilitator: TFacilitator,
208    base_url: Option<Arc<Url>>,
209    price_source: TSource,
210    resource: Arc<ResourceInfoBuilder>,
211}
212
213impl<TFacilitator> X402LayerBuilder<StaticPriceTags, TFacilitator> {
214    /// Adds another payment option.
215    ///
216    /// Allows specifying multiple accepted payment methods (e.g., different networks).
217    ///
218    /// Note: This method is only available for static price tag sources.
219    #[must_use]
220    pub fn with_price_tag(mut self, price_tag: v2::PriceTag) -> Self {
221        self.price_source = self.price_source.with_price_tag(price_tag);
222        self
223    }
224}
225
226#[allow(missing_debug_implementations)] // generic types may not implement Debug
227impl<TSource, TFacilitator> X402LayerBuilder<TSource, TFacilitator> {
228    /// Sets a description of what the payment grants access to.
229    ///
230    /// This is included in 402 responses to inform clients what they're paying for.
231    #[must_use]
232    pub fn with_description(mut self, description: String) -> Self {
233        let mut new_resource = (*self.resource).clone();
234        new_resource.description = description;
235        self.resource = Arc::new(new_resource);
236        self
237    }
238
239    /// Sets the MIME type of the protected resource.
240    ///
241    /// Defaults to `application/json` if not specified.
242    #[must_use]
243    pub fn with_mime_type(mut self, mime: String) -> Self {
244        let mut new_resource = (*self.resource).clone();
245        new_resource.mime_type = mime;
246        self.resource = Arc::new(new_resource);
247        self
248    }
249
250    /// Sets the full URL of the protected resource.
251    ///
252    /// When set, this URL is used directly instead of constructing it from the base URL
253    /// and request URI. This is the preferred approach in production.
254    #[must_use]
255    #[allow(clippy::needless_pass_by_value)] // Url consumed via to_string()
256    pub fn with_resource(mut self, resource: Url) -> Self {
257        let mut new_resource = (*self.resource).clone();
258        new_resource.url = Some(resource.to_string());
259        self.resource = Arc::new(new_resource);
260        self
261    }
262}
263
264impl<S, TSource, TFacilitator> Layer<S> for X402LayerBuilder<TSource, TFacilitator>
265where
266    S: Service<Request, Response = Response, Error = Infallible> + Clone + Send + Sync + 'static,
267    S::Future: Send + 'static,
268    TFacilitator: Facilitator + Clone,
269    TSource: PriceTagSource,
270{
271    type Service = X402MiddlewareService<TSource, TFacilitator>;
272
273    fn layer(&self, inner: S) -> Self::Service {
274        X402MiddlewareService {
275            facilitator: self.facilitator.clone(),
276            base_url: self.base_url.clone(),
277            price_source: self.price_source.clone(),
278            resource: Arc::clone(&self.resource),
279            inner: BoxCloneSyncService::new(inner),
280        }
281    }
282}
283
284/// Axum service that enforces x402 payments on incoming requests.
285///
286/// Generic over `TSource` which implements [`PriceTagSource`] to support
287/// both static and dynamic pricing strategies.
288#[derive(Clone)]
289#[allow(missing_debug_implementations)] // BoxCloneSyncService does not implement Debug
290pub struct X402MiddlewareService<TSource, TFacilitator> {
291    /// Payment facilitator (local or remote)
292    facilitator: TFacilitator,
293    /// Base URL for constructing resource URLs
294    base_url: Option<Arc<Url>>,
295    /// Price tag source - can be static or dynamic
296    price_source: TSource,
297    /// Resource information
298    resource: Arc<ResourceInfoBuilder>,
299    /// The inner Axum service being wrapped
300    inner: BoxCloneSyncService<Request, Response, Infallible>,
301}
302
303impl<TSource, TFacilitator> Service<Request> for X402MiddlewareService<TSource, TFacilitator>
304where
305    TSource: PriceTagSource,
306    TFacilitator: Facilitator + Clone + Send + Sync + 'static,
307{
308    type Response = Response;
309    type Error = Infallible;
310    type Future = Pin<Box<dyn Future<Output = Result<Response, Infallible>> + Send>>;
311
312    /// Delegates readiness polling to the wrapped inner service.
313    fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
314        self.inner.poll_ready(cx)
315    }
316
317    /// Intercepts the request, injects payment enforcement logic, and forwards to the wrapped service.
318    fn call(&mut self, req: Request) -> Self::Future {
319        let price_source = self.price_source.clone();
320        let facilitator = self.facilitator.clone();
321        let base_url = self.base_url.clone();
322        let resource_builder = Arc::clone(&self.resource);
323        let mut inner = self.inner.clone();
324
325        Box::pin(async move {
326            // Resolve price tags from the source
327            let accepts = price_source
328                .resolve(req.headers(), req.uri(), base_url.as_deref())
329                .await;
330
331            // If no price tags are configured, bypass payment enforcement
332            if accepts.is_empty() {
333                return inner.call(req).await;
334            }
335
336            let resource = resource_builder.as_resource_info(base_url.as_deref(), &req);
337
338            let gate = {
339                let mut gate = Paygate::builder(facilitator)
340                    .accepts(accepts)
341                    .resource(resource)
342                    .build();
343                gate.enrich_accepts().await;
344                gate
345            };
346            gate.handle_request(inner, req).await
347        })
348    }
349}
r402_http/server/layer.rs

r402_http/server/
layer.rs
