Struct tide_disco::app::App

source ·
pub struct App<State, Error> { /* private fields */ }
Expand description

A tide-disco server application.

An App is a collection of API modules, plus a global State. Modules can be registered by constructing an Api for each module and calling App::register_module. Once all of the desired modules are registered, the app can be converted into an asynchronous server task using App::serve.

Note that the App is bound to a binary serialization version VER. This format only applies to application-level endpoints like /version and /healthcheck. The binary format version in use by any given API module may differ, depending on the supported version of the API.

Implementations§

source§

impl<State: Send + Sync + 'static, Error: 'static> App<State, Error>

source

pub fn with_state(state: State) -> Self

Create a new App with a given state.

source

pub fn module<'a, ModuleError, ModuleVersion>( &'a mut self, base_url: &'a str, api: impl Into<Value>, ) -> Result<Module<'a, State, Error, ModuleError, ModuleVersion>, AppError>
where Error: Error + From<ModuleError>, ModuleError: Send + Sync + 'static, ModuleVersion: StaticVersionType + 'static,

Create and register an API module.

Creates a new Api with the given api specification and returns an RAII guard for this API. The guard can be used to access the API module, configure it, and populate its handlers. When Module::register is called on the guard (or the guard is dropped), the module will be registered in this App as if by calling register_module.

source

pub fn register_module<ModuleError, ModuleVersion>( &mut self, base_url: &str, api: Api<State, ModuleError, ModuleVersion>, ) -> Result<&mut Self, AppError>
where Error: Error + From<ModuleError>, ModuleError: Send + Sync + 'static, ModuleVersion: StaticVersionType + 'static,

Register an API module.

The module api will be registered as an implementation of the module hosted under the URL prefix base_url.

§Versioning

Multiple versions of the same Api may be registered by calling this function several times with the same base_url, and passing in different APIs which must have different major versions. The API version can be set using Api::with_version.

When multiple versions of the same API are registered, requests for endpoints directly under the base URL, like GET /base_url/endpoint, will always be dispatched to the latest available version of the API. There will in addition be an extension of base_url for each major version registered, so GET /base_url/v1/endpoint will always dispatch to the endpoint handler in the module with major version 1, if it exists, regardless of what the latest version is.

It is an error to register multiple versions of the same module with the same major version. It is not an error to register non-sequential versions of a module. For example, you could have /base_url/v2 and /base_url/v4, but not v1 or v3. Requests for v1 or v3 will simply fail.

The intention of this functionality is to allow for non-disruptive breaking updates. Rather than deploying a new major version of the API with breaking changes in place of the old version, breaking all your clients, you can continue to serve the old version for some period of time under a version prefix. Clients can point at this version prefix until they update their software to use the new version, on their own time.

Note that non-breaking changes (e.g. new endpoints) can be deployed in place of an existing API without even incrementing the major version. The need for serving two versions of an API simultaneously only arises when you have breaking changes.

source

pub fn with_version(&mut self, version: Version) -> &mut Self

Set the application version.

The version information will automatically be included in responses to GET /version.

This is the version of the overall application, which may encompass several APIs, each with their own version. Changes to the version of any of the APIs which make up this application should imply a change to the application version, but the application version may also change without changing any of the API versions.

This version is optional, as the /version endpoint will automatically include the version of each registered API, which is usually enough to uniquely identify the application. Set this explicitly if you want to track the version of additional behavior or interfaces which are not encompassed by the sub-modules of this application.

If you set an application version, it is a good idea to use the version of the application crate found in Cargo.toml. This can be automatically found at build time using the environment variable CARGO_PKG_VERSION and the env! macro. As long as the following code is contained in the application crate, it should result in a reasonable version:

app.with_version(env!("CARGO_PKG_VERSION").parse().unwrap());
source

pub fn version(&self) -> AppVersion

Get the version of this application.

source

pub async fn health(&self, req: RequestParams, state: &State) -> AppHealth

Check the health of each registered module in response to a request.

The response includes a status code for each module, which will be StatusCode::OK if the module is healthy. Detailed health status from each module is not included in the response (due to type erasure) but can be queried using module_health or by hitting the endpoint GET /:module/healthcheck.

source

pub async fn module_health( &self, req: RequestParams, state: &State, module: &str, major_version: Option<u64>, ) -> Option<Response>

Check the health of the named module.

The resulting Response has a status code which is StatusCode::OK if the module is healthy. The response body is constructed from the results of the module’s registered healthcheck handler. If the module does not have an explicit healthcheck handler, the response will be a HealthStatus.

major_version can be used to query the health status of a specific version of the desired module. If it is not provided, the most recent supported version will be queried.

If there is no module with the given name or version, returns None.

source§

impl<State, Error> App<State, Error>
where State: Send + Sync + 'static, Error: 'static + Error,

source

pub async fn serve<L, VER>(self, listener: L, bind_version: VER) -> Result<()>
where L: ToListener<Arc<Self>>, VER: StaticVersionType + 'static,

Serve the App asynchronously.

VER controls the binary format version used for responses to top-level endpoints like /version and /healthcheck. All endpoints for specific API modules will use the format version of that module (ModuleVersion when the module was registered).

Trait Implementations§

source§

impl<State: Debug, Error: Debug> Debug for App<State, Error>

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl<State, Error> Freeze for App<State, Error>

§

impl<State, Error> !RefUnwindSafe for App<State, Error>

§

impl<State, Error> Send for App<State, Error>
where State: Sync + Send,

§

impl<State, Error> Sync for App<State, Error>
where State: Sync + Send,

§

impl<State, Error> Unpin for App<State, Error>

§

impl<State, Error> !UnwindSafe for App<State, Error>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

§

impl<D> OwoColorize for D

§

fn fg<C>(&self) -> FgColorDisplay<'_, C, Self>
where C: Color,

Set the foreground color generically Read more
§

fn bg<C>(&self) -> BgColorDisplay<'_, C, Self>
where C: Color,

Set the background color generically. Read more
§

fn black<'a>(&'a self) -> FgColorDisplay<'a, Black, Self>

Change the foreground color to black
§

fn on_black<'a>(&'a self) -> BgColorDisplay<'a, Black, Self>

Change the background color to black
§

fn red<'a>(&'a self) -> FgColorDisplay<'a, Red, Self>

Change the foreground color to red
§

fn on_red<'a>(&'a self) -> BgColorDisplay<'a, Red, Self>

Change the background color to red
§

fn green<'a>(&'a self) -> FgColorDisplay<'a, Green, Self>

Change the foreground color to green
§

fn on_green<'a>(&'a self) -> BgColorDisplay<'a, Green, Self>

Change the background color to green
§

fn yellow<'a>(&'a self) -> FgColorDisplay<'a, Yellow, Self>

Change the foreground color to yellow
§

fn on_yellow<'a>(&'a self) -> BgColorDisplay<'a, Yellow, Self>

Change the background color to yellow
§

fn blue<'a>(&'a self) -> FgColorDisplay<'a, Blue, Self>

Change the foreground color to blue
§

fn on_blue<'a>(&'a self) -> BgColorDisplay<'a, Blue, Self>

Change the background color to blue
§

fn magenta<'a>(&'a self) -> FgColorDisplay<'a, Magenta, Self>

Change the foreground color to magenta
§

fn on_magenta<'a>(&'a self) -> BgColorDisplay<'a, Magenta, Self>

Change the background color to magenta
§

fn purple<'a>(&'a self) -> FgColorDisplay<'a, Magenta, Self>

Change the foreground color to purple
§

fn on_purple<'a>(&'a self) -> BgColorDisplay<'a, Magenta, Self>

Change the background color to purple
§

fn cyan<'a>(&'a self) -> FgColorDisplay<'a, Cyan, Self>

Change the foreground color to cyan
§

fn on_cyan<'a>(&'a self) -> BgColorDisplay<'a, Cyan, Self>

Change the background color to cyan
§

fn white<'a>(&'a self) -> FgColorDisplay<'a, White, Self>

Change the foreground color to white
§

fn on_white<'a>(&'a self) -> BgColorDisplay<'a, White, Self>

Change the background color to white
§

fn default_color<'a>(&'a self) -> FgColorDisplay<'a, Default, Self>

Change the foreground color to the terminal default
§

fn on_default_color<'a>(&'a self) -> BgColorDisplay<'a, Default, Self>

Change the background color to the terminal default
§

fn bright_black<'a>(&'a self) -> FgColorDisplay<'a, BrightBlack, Self>

Change the foreground color to bright black
§

fn on_bright_black<'a>(&'a self) -> BgColorDisplay<'a, BrightBlack, Self>

Change the background color to bright black
§

fn bright_red<'a>(&'a self) -> FgColorDisplay<'a, BrightRed, Self>

Change the foreground color to bright red
§

fn on_bright_red<'a>(&'a self) -> BgColorDisplay<'a, BrightRed, Self>

Change the background color to bright red
§

fn bright_green<'a>(&'a self) -> FgColorDisplay<'a, BrightGreen, Self>

Change the foreground color to bright green
§

fn on_bright_green<'a>(&'a self) -> BgColorDisplay<'a, BrightGreen, Self>

Change the background color to bright green
§

fn bright_yellow<'a>(&'a self) -> FgColorDisplay<'a, BrightYellow, Self>

Change the foreground color to bright yellow
§

fn on_bright_yellow<'a>(&'a self) -> BgColorDisplay<'a, BrightYellow, Self>

Change the background color to bright yellow
§

fn bright_blue<'a>(&'a self) -> FgColorDisplay<'a, BrightBlue, Self>

Change the foreground color to bright blue
§

fn on_bright_blue<'a>(&'a self) -> BgColorDisplay<'a, BrightBlue, Self>

Change the background color to bright blue
§

fn bright_magenta<'a>(&'a self) -> FgColorDisplay<'a, BrightMagenta, Self>

Change the foreground color to bright magenta
§

fn on_bright_magenta<'a>(&'a self) -> BgColorDisplay<'a, BrightMagenta, Self>

Change the background color to bright magenta
§

fn bright_purple<'a>(&'a self) -> FgColorDisplay<'a, BrightMagenta, Self>

Change the foreground color to bright purple
§

fn on_bright_purple<'a>(&'a self) -> BgColorDisplay<'a, BrightMagenta, Self>

Change the background color to bright purple
§

fn bright_cyan<'a>(&'a self) -> FgColorDisplay<'a, BrightCyan, Self>

Change the foreground color to bright cyan
§

fn on_bright_cyan<'a>(&'a self) -> BgColorDisplay<'a, BrightCyan, Self>

Change the background color to bright cyan
§

fn bright_white<'a>(&'a self) -> FgColorDisplay<'a, BrightWhite, Self>

Change the foreground color to bright white
§

fn on_bright_white<'a>(&'a self) -> BgColorDisplay<'a, BrightWhite, Self>

Change the background color to bright white
§

fn bold<'a>(&'a self) -> BoldDisplay<'a, Self>

Make the text bold
§

fn dimmed<'a>(&'a self) -> DimDisplay<'a, Self>

Make the text dim
§

fn italic<'a>(&'a self) -> ItalicDisplay<'a, Self>

Make the text italicized
§

fn underline<'a>(&'a self) -> UnderlineDisplay<'a, Self>

Make the text italicized
Make the text blink
Make the text blink (but fast!)
§

fn reversed<'a>(&'a self) -> ReversedDisplay<'a, Self>

Swap the foreground and background colors
§

fn hidden<'a>(&'a self) -> HiddenDisplay<'a, Self>

Hide the text
§

fn strikethrough<'a>(&'a self) -> StrikeThroughDisplay<'a, Self>

Cross out the text
§

fn color<Color>(&self, color: Color) -> FgDynColorDisplay<'_, Color, Self>
where Color: DynColor,

Set the foreground color at runtime. Only use if you do not know which color will be used at compile-time. If the color is constant, use either OwoColorize::fg or a color-specific method, such as OwoColorize::green, Read more
§

fn on_color<Color>(&self, color: Color) -> BgDynColorDisplay<'_, Color, Self>
where Color: DynColor,

Set the background color at runtime. Only use if you do not know what color to use at compile-time. If the color is constant, use either OwoColorize::bg or a color-specific method, such as OwoColorize::on_yellow, Read more
§

fn fg_rgb<const R: u8, const G: u8, const B: u8>( &self, ) -> FgColorDisplay<'_, CustomColor<R, G, B>, Self>

Set the foreground color to a specific RGB value.
§

fn bg_rgb<const R: u8, const G: u8, const B: u8>( &self, ) -> BgColorDisplay<'_, CustomColor<R, G, B>, Self>

Set the background color to a specific RGB value.
§

fn truecolor(&self, r: u8, g: u8, b: u8) -> FgDynColorDisplay<'_, Rgb, Self>

Sets the foreground color to an RGB value.
§

fn on_truecolor(&self, r: u8, g: u8, b: u8) -> BgDynColorDisplay<'_, Rgb, Self>

Sets the background color to an RGB value.
§

fn style(&self, style: Style) -> Styled<&Self>

Apply a runtime-determined style
source§

impl<T> Same for T

§

type Output = T

Should always be Self
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more