ratpack/
lib.rs

1/// Application/Server-level management and routing configuration and testing support; outermost functionality.
2pub mod app;
3/// Handler construction and prototypes
4pub mod handler;
5/// Macros for quality-of-life when interacting with Handlers
6pub mod macros;
7/// Path management for Routes
8pub(crate) mod path;
9/// Router, Route management and organization
10pub(crate) mod router;
11
12use http::{Request, Response};
13use std::{collections::BTreeMap, pin::Pin};
14
15/// Params are a mapping of name -> parameter for the purposes of routing.
16pub type Params = BTreeMap<String, String>;
17
18pub(crate) type PinBox<F> = Pin<Box<F>>;
19
20/// An error for server-related issues.
21#[derive(Debug, Clone)]
22pub struct ServerError(String);
23
24impl<T> From<T> for ServerError
25where
26    T: ToString,
27{
28    fn from(t: T) -> Self {
29        ServerError(t.to_string())
30    }
31}
32
33/// General errors for ratpack handlers. Yield either a StatusCode for a literal status, or a
34/// String for a 500 Internal Server Error. Other status codes should be yielded through
35/// [http::Response] returns.
36#[derive(Clone, Debug)]
37pub enum Error {
38    StatusCode(http::StatusCode, String),
39    InternalServerError(String),
40}
41
42impl Default for Error {
43    fn default() -> Self {
44        Self::InternalServerError("internal server error".to_string())
45    }
46}
47
48impl Error {
49    /// Convenience method to pass anything in that accepts a .to_string method.
50    pub fn new<T>(message: T) -> Self
51    where
52        T: ToString,
53    {
54        Self::InternalServerError(message.to_string())
55    }
56
57    /// A convenient way to return status codes with optional informational bodies.
58    pub fn new_status<T>(error: http::StatusCode, message: T) -> Self
59    where
60        T: ToString,
61    {
62        Self::StatusCode(error, message.to_string())
63    }
64}
65
66impl<T> From<T> for Error
67where
68    T: ToString,
69{
70    fn from(t: T) -> Self {
71        Self::new(t.to_string())
72    }
73}
74
75pub trait ToStatus
76where
77    Self: ToString,
78{
79    fn to_status(&self) -> Error;
80}
81
82/// HTTPResult is the return type for handlers. If a handler terminates at the end of its chain
83/// with [std::option::Option::None] as the [http::Response], a 500 Internal Server Error will be
84/// returned. If you wish to return Err(), a [http::StatusCode] or [std::string::String] can be
85/// returned, the former is resolved to its status with an empty body, and the latter corresponds
86/// to a 500 Internal Server Error with the body set to the string.
87pub type HTTPResult<TransientState> = Result<
88    (
89        Request<hyper::Body>,
90        Option<Response<hyper::Body>>,
91        TransientState,
92    ),
93    Error,
94>;
95
96/// TransientState must be implemented to use state between handlers.
97pub trait TransientState
98where
99    Self: Clone + Send,
100{
101    /// initial prescribes an initial state for the trait, allowing it to be constructed at
102    /// dispatch time.
103    fn initial() -> Self;
104}
105
106/// NoState is an empty [crate::TransientState].
107#[derive(Clone)]
108pub struct NoState;
109
110impl TransientState for NoState {
111    fn initial() -> Self {
112        Self {}
113    }
114}
115
116/// A convenience import to gather all of `ratpack`'s dependencies in one easy place.
117/// To use:
118///
119/// ```
120///     use ratpack::prelude::*;
121/// ```
122pub mod prelude {
123    pub use crate::{
124        app::App, compose_handler, Error, HTTPResult, NoState, Params, ServerError, ToStatus,
125        TransientState,
126    };
127    pub use http::{Request, Response, StatusCode};
128    pub use hyper::Body;
129}
ratpack/lib.rs

ratpack/
lib.rs
