surf_disco/
lib.rs

1// Copyright (c) 2022 Espresso Systems (espressosys.com)
2// This file is part of the surf-disco library.
3
4// You should have received a copy of the MIT License
5// along with the surf-disco library. If not, see <https://mit-license.org/>.
6
7//! Surf Disco: a client library for [Tide Disco](https://tide-disco.docs.espressosys.com/tide_disco/) applications.
8//!
9//! # Quick Start
10//!
11//! ```
12//! # use surf_disco::{Client, error::ClientError};
13//! # use vbs::version::StaticVersion;
14//! # async fn ex() {
15//! let url = "http://localhost:50000".parse().unwrap();
16//! let client: Client<ClientError, StaticVersion<0,1>> = Client::new(url);
17//! let res: String = client.get("/app/route").send().await.unwrap();
18//! # }
19//! ```
20//!
21use serde::de::DeserializeOwned;
22use std::time::Duration;
23use vbs::version::StaticVersionType;
24
25pub mod client;
26pub mod error;
27pub mod reexports;
28pub mod request;
29pub mod socket;
30
31pub use client::{Client, ContentType};
32pub use error::Error;
33pub use request::Request;
34pub use socket::SocketRequest;
35pub use tide_disco::{
36    http::{self, Method},
37    StatusCode, Url,
38};
39
40/// Build an HTTP `GET` request.
41pub fn get<T: DeserializeOwned, E: Error, VER: StaticVersionType>(url: Url) -> Request<T, E, VER> {
42    Client::new(url).get("/")
43}
44
45/// Build an HTTP `POST` request.
46pub fn post<T: DeserializeOwned, E: Error, VER: StaticVersionType>(url: Url) -> Request<T, E, VER> {
47    Client::new(url).post("/")
48}
49
50/// Connect to a server, retrying if the server is not running.
51///
52/// This function will make an HTTP `GET` request to the server's `/healthcheck` endpoint, to test
53/// if the server is available. If this request succeeds, [connect] returns `true`. Otherwise, the
54/// client will continue retrying `/healthcheck` requests until `timeout` has elapsed (or forever,
55/// if `timeout` is `None`). If the timeout expires before a `/healthcheck` request succeeds,
56/// [connect] will return `false`.
57pub async fn connect<E: Error, VER: StaticVersionType>(
58    url: Url,
59    timeout: Option<Duration>,
60) -> bool {
61    Client::<E, VER>::new(url).connect(timeout).await
62}