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
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
//! [![crates.io](https://img.shields.io/crates/v/bollard.svg)](https://crates.io/crates/bollard)
//! [![license](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
//! [![circle-ci](https://circleci.com/gh/fussybeaver/bollard/tree/master.svg?style=svg)](https://circleci.com/gh/fussybeaver/bollard/tree/master)
//! [![appveyor](https://ci.appveyor.com/api/projects/status/n5khebyfae0u1sbv/branch/master?svg=true)](https://ci.appveyor.com/project/fussybeaver/boondock)
//! [![docs](https://docs.rs/bollard/badge.svg)](https://docs.rs/bollard/)
//!
//! # Bollard: an asynchronous rust client library for the docker API
//!
//! Bollard leverages the latest [Hyper](https://github.com/hyperium/hyper) and
//! [Tokio](https://github.com/tokio-rs/tokio) improvements for an asynchronous API containing
//! futures, streams and the async/await paradigm.
//!
//! This library features Windows support through [Named
//! Pipes](https://learn.microsoft.com/en-us/windows/win32/ipc/named-pipes) and HTTPS support through optional
//! [Rustls](https://github.com/rustls/rustls) bindings. Serialization types for interfacing with
//! [Docker](https://github.com/moby/moby) and [Buildkit](https://github.com/moby/buildkit) are
//! generated through OpenAPI, protobuf and upstream documentation.
//!
//!
//!
//! # Install
//!
//! Add the following to your `Cargo.toml` file
//!
//! ```nocompile
//! [dependencies]
//! bollard = "*"
//! ```
//!
//! # API
//! ## Documentation
//!
//! [API docs](https://docs.rs/bollard/).
//!
//! ### Latest
//!
//! Version `0.14` enables a `buildkit` feature for builds using public images (check the
//! [buildkit example](https://github.com/fussybeaver/bollard/blob/v0.14.0/examples/build_buildkit.rs)
//! for details on how to configure).
//!
//! ## Feature flags
//!
//!  - `ssl`: enable SSL support through [Rustls](https://github.com/rustls/rustls)
//!  - `chrono`: enable [Chrono](https://github.com/chronotope/chrono) for `DateTime` types.
//!  - `time`: enable [Time 0.3](https://github.com/time-rs/time) for `DateTime` types.
//!  - `buildkit`: use [Buildkit](https://github.com/moby/buildkit) instead of
//!    [Docker](https://github.com/moby/moby) when building images.
//!  - `json_data_content`: Add JSON to errors on serialization failures.
//!  - `ct_logs`: [Certificate transparency](https://certificate.transparency.dev/howctworks/)
//!    verification (requires `ssl`).
//!
//! ## Version
//!
//! The [Docker API](https://docs.docker.com/engine/api/v1.41/) used by Bollard is using the latest
//! `1.41` documentation schema published by the [moby](https://github.com/moby/moby) project to
//! generate its serialization interface.
//!
//! This library also supports [version
//! negotiation](https://docs.rs/bollard/latest/bollard/struct.Docker.html#method.negotiate_version),
//! to allow downgrading to an older API version.
//!
//! # Usage
//!
//! ## Connecting with the docker daemon
//!
//! Connect to the docker server according to your architecture and security remit.
//!
//! ### Socket
//!
//! The client will connect to the standard unix socket location `/var/run/docker.sock` or Windows
//! named pipe location `//./pipe/docker_engine`.
//!
//! ```rust
//! use bollard::Docker;
//! #[cfg(unix)]
//! Docker::connect_with_socket_defaults();
//! ```
//!
//! Use the `Docker::connect_with_socket` method API to parameterise this interface.
//!
//! ### Local
//!
//! The client will connect to the OS specific handler it is compiled for.
//!
//! This is a convenience for localhost environment that should run on multiple
//! operating systems.
//!
//! ```rust
//! use bollard::Docker;
//! Docker::connect_with_local_defaults();
//! ```
//!
//! Use the `Docker::connect_with_local` method API to parameterise this interface.
//!
//! ### HTTP
//!
//! The client will connect to the location pointed to by `DOCKER_HOST` environment variable, or
//! `localhost:2375` if missing.
//!
//! ```rust
//! use bollard::Docker;
//! Docker::connect_with_http_defaults();
//! ```
//!
//! Use the `Docker::connect_with_http` method API to parameterise the interface.
//!
//! ### SSL via Rustls
//!
//! The client will connect to the location pointed to by `DOCKER_HOST` environment variable, or
//! `localhost:2375` if missing.
//!
//! The location pointed to by the `DOCKER_CERT_PATH` environment variable is searched for
//! certificates - `key.pem` for the private key, `cert.pem` for the server certificate and
//! `ca.pem` for the certificate authority chain.
//!
//! ```rust
//! use bollard::Docker;
//! #[cfg(feature = "ssl")]
//! Docker::connect_with_ssl_defaults();
//! ```
//!
//! Use the `Docker::connect_with_ssl` method API to parameterise the interface.
//!
//! ## Examples
//!
//! Note: all these examples need a [Tokio
//! Runtime](https://tokio.rs/).
//!
//! ### Version
//!
//! First, check that the API is working with your server:
//!
//! ```rust,no_run
//! use bollard::Docker;
//!
//! use futures_util::future::FutureExt;
//!
//! // Use a connection function described above
//! // let docker = Docker::connect_...;
//! # let docker = Docker::connect_with_local_defaults().unwrap();
//!
//! async move {
//!     let version = docker.version().await.unwrap();
//!     println!("{:?}", version);
//! };
//! ```
//!
//! ### Listing images
//!
//! To list docker images available on the Docker server:
//!
//! ```rust,no_run
//! use bollard::Docker;
//! use bollard::image::ListImagesOptions;
//!
//! use futures_util::future::FutureExt;
//!
//! use std::default::Default;
//!
//! // Use a connection function described above
//! // let docker = Docker::connect_...;
//! # let docker = Docker::connect_with_local_defaults().unwrap();
//!
//! async move {
//!     let images = &docker.list_images(Some(ListImagesOptions::<String> {
//!         all: true,
//!         ..Default::default()
//!     })).await.unwrap();
//!
//!     for image in images {
//!         println!("-> {:?}", image);
//!     }
//! };
//! ```
//!
//! ## Streaming Stats
//!
//! To receive a stream of stats for a running container.
//!
//! ```rust,no_run
//! use bollard::Docker;
//! use bollard::container::StatsOptions;
//!
//! use futures_util::stream::TryStreamExt;
//!
//! use std::default::Default;
//!
//! // Use a connection function described above
//! // let docker = Docker::connect_...;
//! # let docker = Docker::connect_with_local_defaults().unwrap();
//!
//! async move {
//!     let stats = &docker.stats("postgres", Some(StatsOptions {
//!        stream: true,
//!        ..Default::default()
//!     })).try_collect::<Vec<_>>().await.unwrap();
//!
//!     for stat in stats {
//!         println!("{} - mem total: {:?} | mem usage: {:?}",
//!             stat.name,
//!             stat.memory_stats.max_usage,
//!             stat.memory_stats.usage);
//!     }
//! };
//! ```
//!
//! # Examples
//!
//! Further examples are available in the [examples
//! folder](https://github.com/fussybeaver/bollard/tree/master/examples), or the [integration/unit
//! tests](https://github.com/fussybeaver/bollard/tree/master/tests).
//!
//! # Development
//!
//! Contributions are welcome, please observe the following.
//!
//! ## Building the proto models
//!
//! Serialization models for the buildkit feature are generated through the [Tonic
//! library](https://github.com/hyperium/tonic/). To generate these files, use the
//! following in the `codegen/proto` folder:
//!
//! ```bash
//! cargo run --bin gen --features build
//! ```
//!
//! ## Building the swagger models
//!
//! Serialization models are generated through the [Swagger
//! library](https://github.com/swagger-api/swagger-codegen/). To generate these files, use the
//! following in the `codegen/swagger` folder:
//!
//! ```bash
//! mvn -D org.slf4j.simpleLogger.defaultLogLevel=error compiler:compile generate-resources
//! ```
//!
//! # Integration tests
//!
//! Running the integration tests by default requires a running docker registry, with images tagged
//! and pushed there. To disable this behaviour, set the `DISABLE_REGISTRY` environment variable.
//!
//! ```bash
//! docker run -d --restart always --name registry -p 5000:5000 registry:2
//! docker pull hello-world:linux
//! docker pull fussybeaver/uhttpd
//! docker pull alpine
//! docker tag hello-world:linux localhost:5000/hello-world:linux
//! docker tag fussybeaver/uhttpd localhost:5000/fussybeaver/uhttpd
//! docker tag alpine localhost:5000/alpine
//! docker push localhost:5000/hello-world:linux
//! docker push localhost:5000/fussybeaver/uhttpd
//! docker push localhost:5000/alpine
//! docker swarm init
//! REGISTRY_HTTP_ADDR=localhost:5000 cargo test -- --test-threads 1
//! ```
#![deny(
    missing_docs,
    missing_debug_implementations,
    missing_copy_implementations,
    trivial_casts,
    trivial_numeric_casts,
    unstable_features,
    unused_import_braces,
    unused_qualifications
)]
#![allow(clippy::upper_case_acronyms, clippy::derive_partial_eq_without_eq)]
#![warn(rust_2018_idioms)]

#[macro_use]
extern crate serde_derive;
#[macro_use]
extern crate log;

// declare modules
pub mod auth;
pub mod container;
mod docker;
pub mod errors;
pub mod exec;
pub mod image;
mod named_pipe;
pub mod network;
mod read;
pub mod secret;
pub mod service;
pub mod system;
mod uri;
pub mod volume;

pub mod grpc;

// publicly re-export
pub use crate::docker::{ClientVersion, Docker, API_DEFAULT_VERSION};
pub use bollard_stubs::models;

#[cfg(feature = "buildkit")]
pub use bollard_buildkit_proto::health;

#[cfg(feature = "buildkit")]
pub use bollard_buildkit_proto::moby;