1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95
//! Definition of Connector and Connection. //! //! The rincon driver uses a connector that implements the communication layer //! to the ArangoDB server. It defines the transport protocol like HTTP or HTTPS //! and the format for serializing the payload of requests and responses, like //! JSON for example. //! //! A connector establishes connections to a server. A connection is used to //! actually execute a method call. //! //! A connector is defined to implement the `Connector` trait. A connection as //! established and provided by a `Connector` is of type `Connector::Connection` //! The `Connection` type is bound to implement the `Execute` trait. //! //! Depending on the implementation of a connector it can be simply a factory //! for connections or be more advanced by maintaining a pool of connections. //! //! Implementations of a connection know how to serialize and send method calls //! to the server and deserialize the responses into the defined result type. use std::io; use futures::Future; use api; use api::auth::Jwt; use api::method::{Method, Prepare}; /// A connector establishes and provides connections to a server. pub trait Connector { /// The type of connections this connector provides. type Connection: 'static + Execute; /// Establishes a connection to the database with the given name and returns /// the connection. /// /// More sophisticated implementations may also maintain a pool of /// connections and return available connections from that pool. fn connection(&self, database_name: &str) -> Self::Connection; /// Establishes a connection to the system database as defined by ArangoDB /// and returns the connection. fn system_connection(&self) -> Self::Connection; /// Tells this connector to use the given token for authentication. fn use_auth_token(&mut self, token: Jwt); /// Tells this connector to no longer use the configured token for /// authentication. fn invalidate_auth_token(&mut self); } /// A type that can execute method calls. /// /// Any type that implements this `Execute` trait can be returned by the /// `Connector` as `Connector::Connection`. pub trait Execute { /// Executes the given method asynchronously and returns a future result. fn execute<M>(&self, method: M) -> FutureResult<M> where M: 'static + Method + Prepare; } /// The result of any asynchronous method call pub type FutureResult<M> = Box<Future<Item=<M as Method>::Result, Error=Error>>; /// The type of error that can occur during communication with the server. #[derive(Debug, Clone, PartialEq, Eq, Fail)] pub enum Error { /// A communication error like server not responding or IO error. #[fail(display = "Communication failed: {}", _0)] Communication(String), /// An error that occurs during deserialization of a response. #[fail(display = "Deserialization failed: {}", _0)] Deserialization(String), /// An error that occurs during method execution. /// /// This error signals ArangoDB specific errors like AQL syntax error or /// document not found. #[fail(display = "Execution of method failed: {}", _0)] Method(api::Error), /// The caller is not authenticated to the server. #[fail(display = "Not authenticated to datasource: {}", _0)] NotAuthenticated(String), /// An error that occurs during serialization of a request. #[fail(display = "Serialization failed: {}", _0)] Serialization(String), /// A timeout occurred during method call execution. #[fail(display = "Timeout on request: {}", _0)] Timeout(String), } impl From<io::Error> for Error { fn from(err: io::Error) -> Self { Error::Communication(err.to_string()) } }