instances_social/

lib.rs

#![deny(missing_docs)]

/*!
Rust API client for the instances.social API

```no_run
use instances_social::Client;

const TOKEN: &'static str = "...";

fn main() {
    let client = Client::new(TOKEN);
    // all the API calls are available like this:
    //
    // client.instances().list()
    // client.instances().sample()
    // client.instances().search()
    // client.instances().show()
    // client.versions().list()
    // client.versions().show()
}
```
*/

#[macro_use]
extern crate serde_derive;

use std::error::Error;

use serde::{Deserialize, Serialize};
use tap_reader::Tap;
use url::{ParseError, Url};

pub mod instances;
pub mod versions;

fn url(path: &str) -> Result<Url, ParseError> {
    let url = format!("https://instances.social/api/1.0/{}", path);
    Url::parse(&url)
}

/// Instances.social client
///
/// requires an API token
pub struct Client {
    token: String,
    client: reqwest::Client,
}

impl Client {
    /// Create a new client from a token
    pub fn new(token: &str) -> Client {
        Client {
            token: token.into(),
            client: reqwest::Client::new(),
        }
    }

    fn token(&self) -> String {
        format!("Bearer {}", self.token)
    }

    /// Access the /versions/* API calls
    pub fn versions(&self) -> Versions {
        Versions(self)
    }

    /// Access the /instances/* API calls
    pub fn instances(&self) -> Instances {
        Instances(self)
    }

    fn get_qs<S: Serialize>(&self, path: &str, data: S) -> Result<reqwest::RequestBuilder, Box<Error>> {
        let mut url = url(path)?;
        let qs = serde_qs::to_string(&data)?;
        url.set_query(Some(qs.as_ref()));
        Ok(self.client.get(url.as_str()).header(reqwest::header::AUTHORIZATION, &self.token()[..]))
    }

    fn send<D>(&self, req: reqwest::RequestBuilder) -> Result<D, Box<Error>>
    where
        for<'de> D: Deserialize<'de>,
    {
        let resp = req.send()?;
        let mut reader = Tap::new(resp);
        Ok(match serde_json::from_reader(&mut reader) {
            Ok(r) => r,
            Err(e) => {
                let err = String::from_utf8_lossy(&reader.bytes);
                eprintln!("error: {:?}\nsource: {}", e, err);
                return Err(e.into());
            }
        })
    }
}

/// Container for the /versions/* API calls
///
/// # List versions
///
/// ```no_run
/// use instances_social::Client;
///
/// const TOKEN: &'static str = "...";
///
/// fn main() -> Result<(), Box<std::error::Error>> {
///     let client = Client::new(TOKEN);
///
///     let result = client.versions()
///         .list() // returns this builder
///         .count(100) // sets the ?count=100 querystring param
///         // ...etc
///         .send()?; // actually sends the request
///     Ok(())
/// }
/// ```
///
/// # Show version
///
/// ```no_run
/// use instances_social::Client;
///
/// const TOKEN: &'static str = "...";
///
/// fn main() -> Result<(), Box<std::error::Error>> {
///     let client = Client::new(TOKEN);
///
///     let result = client.versions()
///         .show("2.7.0") // returns this builder
///         // ...etc
///         .send()?; // actually sends the request
///     Ok(())
/// }
/// ```
pub struct Versions<'a>(&'a Client);
impl<'a> Versions<'a> {
    /// Starts build a versions/list call
    pub fn list(&self) -> versions::ListRequestBuilder {
        versions::ListRequestBuilder::new(self.0)
    }

    /// Starts building a versions/show call
    pub fn show(&self, name: &str) -> versions::ShowRequestBuilder {
        versions::ShowRequestBuilder::new(self.0, name)
    }
}

/// Container for the /instances/* API calls
///
/// # Sample instances
///
/// ```no_run
/// use instances_social::Client;
///
/// const TOKEN: &'static str = "...";
///
/// fn main() -> Result<(), Box<std::error::Error>> {
///     let client = Client::new(TOKEN);
///
///     let result = client.instances()
///         .sample() // returns this builder
///         .count(100) // sets the ?count=100 querystring param
///         // ...etc
///         .send()?; // actually sends the request
///     Ok(())
/// }
/// ```
///
/// # Show instance
///
///
/// ```no_run
/// use instances_social::Client;
///
/// const TOKEN: &'static str = "...";
///
/// fn main() -> Result<(), Box<std::error::Error>> {
///     let client = Client::new(TOKEN);
///
///     let result = client.instances()
///         .show("mastodon.social") // returns this builder
///         .send()?; // actually sends the request
///     Ok(())
/// }
/// ```
///
/// # List instances
///
/// ```no_run
/// use instances_social::Client;
///
/// const TOKEN: &'static str = "...";
///
/// fn main() -> Result<(), Box<std::error::Error>> {
///     let client = Client::new(TOKEN);
///
///     let result = client.instances()
///         .list() // returns this builder
///         .count(100) // sets the ?count=100 querystring param
///         // ...etc
///         .send()?; // actually sends the request
///     Ok(())
/// }
/// ```
///
/// # Search instances
///
/// ```no_run
/// use instances_social::Client;
///
/// const TOKEN: &'static str = "...";
///
/// fn main() -> Result<(), Box<std::error::Error>> {
///     let client = Client::new(TOKEN);
///
///     let result = client.instances()
///         .search("some-query") // returns this builder
///         .count(100) // sets the ?count=100 querystring param
///         // ...etc
///         .send()?; // actually sends the request
///     Ok(())
/// }
/// ```
pub struct Instances<'a>(&'a Client);
impl<'a> Instances<'a> {
    /// Represents a request to the https://instances.social/api/1.0/instances/sample endpoint
    ///
    /// ```no_run
    /// use instances_social::Client;
    ///
    /// const TOKEN: &'static str = "...";
    ///
    /// fn main() -> Result<(), Box<std::error::Error>> {
    ///     let client = Client::new(TOKEN);
    ///
    ///     let result = client.instances()
    ///         .sample() // returns this builder
    ///         .count(100) // sets the ?count=100 querystring param
    ///         // ...etc
    ///         .send()?; // actually sends the request
    ///     Ok(())
    /// }
    /// ```
    pub fn sample(&self) -> instances::SampleRequestBuilder {
        instances::SampleRequestBuilder::new(self.0)
    }

    /// Request builder for the instances/list call
    ///
    /// ```no_run
    /// use instances_social::Client;
    ///
    /// const TOKEN: &'static str = "...";
    ///
    /// fn main() -> Result<(), Box<std::error::Error>> {
    ///     let client = Client::new(TOKEN);
    ///
    ///     let result = client.instances()
    ///         .list() // returns this builder
    ///         .count(100) // sets the ?count=100 querystring param
    ///         // ...etc
    ///         .send()?; // actually sends the request
    ///     Ok(())
    /// }
    /// ```
    pub fn list(&self) -> instances::ListRequestBuilder {
        instances::ListRequestBuilder::new(self.0)
    }

    /// Represents a request to the https://instances.social/api/1.0/instances/search endpoint
    ///
    /// ```no_run
    /// use instances_social::Client;
    ///
    /// const TOKEN: &'static str = "...";
    ///
    /// fn main() -> Result<(), Box<std::error::Error>> {
    ///     let client = Client::new(TOKEN);
    ///
    ///     let result = client.instances()
    ///         .search("some-query") // returns this builder
    ///         .count(100) // sets the ?count=100 querystring param
    ///         // ...etc
    ///         .send()?; // actually sends the request
    ///     Ok(())
    /// }
    /// ```
    pub fn search(&self, q: &str) -> instances::SearchRequestBuilder {
        instances::SearchRequestBuilder::new(self.0, q)
    }

    /// Represents a request to the https://instances.social/api/1.0/instances/show endpoint
    ///
    /// ```no_run
    /// use instances_social::Client;
    ///
    /// const TOKEN: &'static str = "...";
    ///
    /// fn main() -> Result<(), Box<std::error::Error>> {
    ///     let client = Client::new(TOKEN);
    ///
    ///     let result = client.instances()
    ///         .show("mastodon.social") // returns this builder
    ///         .send()?; // actually sends the request
    ///     Ok(())
    /// }
    /// ```
    pub fn show(&self, name: &str) -> instances::ShowRequestBuilder {
        instances::ShowRequestBuilder::new(self.0, name)
    }
}

pub(crate) trait Resp {
    type Item: Clone;

    fn items(&self) -> &Vec<Self::Item>;
    fn next(&self) -> Option<String>;
}

pub(crate) trait ItemIter {
    type Response: Resp;

    fn get_page(&mut self, token: Option<&String>) -> Result<Self::Response, Box<Error>>;
}

pub(crate) struct ItemIterator<I: ItemIter> {
    source: I,
    token: Option<String>,
    init: bool,
    buffer: Vec<<I::Response as Resp>::Item>,
}

impl<I: ItemIter> ItemIterator<I> {
    pub(crate) fn new(source: I) -> ItemIterator<I> {
        ItemIterator {
            source,
            token: None,
            init: false,
            buffer: Vec::new(),
        }
    }

    fn fill_buffer(&mut self) -> Result<(), Box<Error>> {
        if !self.init {
            let page = self.source.get_page(None)?;
            self.buffer.extend_from_slice(page.items());
            self.token = page.next();
            self.init = true;
        }

        if let Some(ref t) = self.token {
            let page = self.source.get_page(Some(t))?;
            self.buffer.extend_from_slice(page.items());
            self.token = page.next();
        }

        Ok(())
    }
}

impl<I> Iterator for ItemIterator<I>
where
    I: ItemIter,
{
    type Item = <<I as ItemIter>::Response as Resp>::Item;

    fn next(&mut self) -> Option<Self::Item> {
        if self.buffer.is_empty() {
            if self.fill_buffer().is_err() {
                return None;
            }
        }
        self.buffer.pop()
    }
}