rincon 0.1.0

An ArangoDB driver for Rust
Documentation 
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
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161


# Rincon - ArangoDB Rust driver

[![Crates.io][crates_badge]][crate]
[![Docs.rs][docs_badge]][documentation]
[![Apache-2.0][license_badge]][Apache-2.0]
[![Join the chat][gitter_badge]][chat]

[crates_badge]: https://img.shields.io/crates/v/rincon.svg
[docs_badge]: https://docs.rs/rincon/badge.svg
[license_badge]: https://img.shields.io/badge/license-Apache%2D%2D2%2E0-blue.svg
[gitter_badge]: https://badges.gitter.im/innoave/rincon.svg

[crate]: https://crates.io/crates/rincon
[documentation]: https://docs.rs/rincon
[Apache-2.0]: https://www.apache.org/licenses/LICENSE-2.0
[chat]: https://gitter.im/innoave/rincon
[license]: ../LICENSE
[Rincon project]: https://github.com/innoave/rincon
[rincon]: ../rincon
[rincon_core]: ../rincon_core
[rincon_connector]: ../rincon_connector
[rincon_client]: ../rincon_client
[rincon_session]: ../rincon_session
[rincon_session_async]: ../rincon_session_async
[rincon_aql]: ../rincon_aql
[rincon_test_helper]: ../rincon_test_helper

[rincon_core API]: https://docs.rs/rincon_core
[rincon_connector API]: https://docs.rs/rincon_connector
[rincon_client API]: https://docs.rs/rincon_client
[rincon_session API]: https://docs.rs/rincon_session
[rincon_session_async API]: https://docs.rs/rincon_session_async
[rincon_aql API]: https://docs.rs/rincon_aql
[rincon_test_helper API]: https://docs.rs/rincon_test_helper

The [rincon] [crate] itself does not provide any functionality. It is meant as an entry point
for the [Rincon project] which aims to provide a complete [ArangoDB] driver for [Rust].

The [Rincon project] provides several crates. You can choose which functionality you want for your
project and which level of abstraction you prefer. The separation into several crates allows to only
import those crates that are needed for your project.

The provided crates are:

* [rincon_core] : Defines the common API for the driver and is used by the other crates.
* [rincon_connector] : Implements the communication layer of the driver.
* [rincon_client] : Implements the methods of the REST API provided by [ArangoDB].
* [rincon_session] : Provides a synchronous higher level API on top of [rincon_client].
* [rincon_session_async] : Provides an asynchronous higher level API on top of [rincon_client].
* [rincon_aql] : Provides a DSL to build [AQL] queries in a typesafe manner. 
* [rincon_test_helper] : Provides utilities used in integration tests with an [ArangoDB] server.

Here is a diagram that depicts the dependencies between the crates:

![Crate dependency structure](../docs/crate_structure.png)

## Getting started

For guides on how to use the Rincon ArangoDB driver check out the documentation
of the [rincon_session API] and the [rincon_client API]. 

## Status of the project

**Currently not all crates listed above are released yet**

The ready and released crates are:

* [rincon_core] : Defines the common API for the driver and is used by the other crates.
* [rincon_connector] : Implements the communication layer of the driver.
* [rincon_client] : Implements the methods of the REST API provided by [ArangoDB].
* [rincon_session] : Provides a synchronous higher level API on top of [rincon_client].
* [rincon_test_helper] : Provides utilities used in integration tests with an [ArangoDB] server.

Crates which are planned but are not ready yet:

* [rincon_session_async] : Provides an asynchronous higher level API on top of [rincon_client].
* [rincon_aql] : Provides a DSL to build [AQL] queries in a typesafe manner. 

## Which crates should I add as dependencies to my project? 

First choose whether you want to use the lower level [rincon_client API] or the higher level 
[rincon_session_async API]. Both of these APIs are asynchronous. That is the methods return
`Future`s (of the Tokio project). If you prefer a synchronous API you might want to use the
[rincon_session API].

Additionally you need a so called connector to communicate with the [ArangoDB] server. Connectors
are provided by the [rincon_connector] crate.

To use the low level client API with a provided connector add this to your `Cargo.toml`:

```toml
[dependencies]
rincon_core = "0.1"
rincon_connector = "0.1"
rincon_client = "0.1"
```

__Note__: The [rincon_client] crate provides several optional crate features.
See the [README](../rincon_client/README.md) of this crate for a list of its crate features and
how to use them.

To use the synchronous session API with a provided connector add this to your `Cargo.toml`:

```toml
[dependencies]
rincon_core = "0.1"
rincon_connector = "0.1"
rincon_session = "0.1"
```

__Note__: As [rincon_session] builds on top of [rincon_client] it re-exports the optional crate
features of [rincon_client]. Thus the same features of [rincon_client] may be applied to the
dependency definition of the [rincon_session] crate as well.
See the [README](../rincon_client/README.md) of the [rincon_client] crate for a list of features and
how to use them.

To use the asynchronous session API with a provided connector add this to your `Cargo.toml`:

```toml
[dependencies]
rincon_core = "0.1"
rincon_connector = "0.1"
rincon_session_async = "0.1"
```

__Note__: As [rincon_session_async] builds on top of [rincon_client] it re-exports the optional crate
features of [rincon_client]. Thus the same features of [rincon_client] may be applied to the
dependency definition of the [rincon_session_async] crate as well.
See the [README](../rincon_client/README.md) of the [rincon_client] crate for a list of features and
how to use them.

With the minimal dependencies described above you can write AQL queries as strings. To make use of
the typesafe AQL query builder add this dependency to your `Cargo.toml`: 

```toml
[dependencies]
rincon_aql = "0.1"
#.. plus rincon dependencies as described above
```

In applications you will not use the [rincon_core] crate directly. But if you want to implement your
own connector instead of using one of the provided ones the custom implementation shall depend on
[rincon_core] only. [rincon_core] is also needed to implement a method of the [ArangoDB] REST API
that is not provided by [rincon_client] yet.

## License

Licensed under Apache License, Version 2.0<br/>
see [LICENSE] or http://www.apache.org/licenses/LICENSE-2.0 for details.

### Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
licensed as above, without any additional terms or conditions.


[ArangoDB]: https://www.arangodb.com
[AQL]: https://docs.arangodb.com/3.2/AQL/index.html
[Rust]: https://www.rust-lang.org