diff --git a/Cargo.toml b/Cargo.toml index eb6cf082..e43ca77d 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "bollard" description = "An asynchronous Docker daemon API" -version = "0.13.0" +version = "0.14.0" authors = [ "Bollard contributors" ] license = "Apache-2.0" homepage = "https://github.com/fussybeaver/bollard" diff --git a/README.md b/README.md index ea1dfdd9..ea572774 100644 --- a/README.md +++ b/README.md @@ -10,8 +10,13 @@ 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. -The library also features Windows support through Named Pipes and HTTPS support through -optional rustls bindings. +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 @@ -19,7 +24,7 @@ Add the following to your `Cargo.toml` file ```nocompile [dependencies] -bollard = "0.13" +bollard = "*" ``` ## API @@ -27,20 +32,30 @@ bollard = "0.13" [API docs](https://docs.rs/bollard/). -Version 0.13 introduces an optional `chrono` and alternative mutually exclusive `time` feature -flag to represent the date format. This version matches the moby v20.10.16 server API. +#### 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). -Version 0.11 re-enables Windows Named Pipe support. +### Feature flags -As of version 0.6, this project now generates API stubs from the upstream Docker-maintained -[Swagger OpenAPI specification](https://docs.docker.com/engine/api/v1.41.yaml). The generated -models are committed to this repository, but packaged in a separate crate -[bollard-stubs](https://crates.io/crates/bollard-stubs). + - `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/) is pegged at version `1.41`. The -library also supports [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. @@ -52,9 +67,8 @@ 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`. Use the `Docker::connect_with_socket` method API -to parameterise the interface. +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; @@ -62,29 +76,34 @@ use bollard::Docker; 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. -Use the `Docker::connect_with_local` method API to parameterise the interface. + ```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. Use the -`Docker::connect_with_http` method API to -parameterise the interface. +`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 @@ -94,15 +113,14 @@ The location pointed to by the `DOCKER_CERT_PATH` environment variable is search certificates - `key.pem` for the private key, `cert.pem` for the server certificate and `ca.pem` for the certificate authority chain. -Use the `Docker::connect_with_ssl` method API -to parameterise the interface. - ```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 @@ -191,7 +209,7 @@ tests](https://github.com/fussybeaver/bollard/tree/master/tests). ## Development -Contributions are welcome, please observe the following advice. +Contributions are welcome, please observe the following. ### Building the proto models diff --git a/src/lib.rs b/src/lib.rs index 0b18aba8..995a35e9 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -10,8 +10,13 @@ //! [Tokio](https://github.com/tokio-rs/tokio) improvements for an asynchronous API containing //! futures, streams and the async/await paradigm. //! -//! The library also features Windows support through Named Pipes and HTTPS support through -//! optional rustls bindings. +//! 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 //! @@ -19,7 +24,7 @@ //! //! ```nocompile //! [dependencies] -//! bollard = "0.13" +//! bollard = "*" //! ``` //! //! # API @@ -27,20 +32,30 @@ //! //! [API docs](https://docs.rs/bollard/). //! -//! Version 0.13 introduces an optional `chrono` and alternative mutually exclusive `time` feature -//! flag to represent the date format. This version matches the moby v20.10.16 server API. +//! ### 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). //! -//! Version 0.11 re-enables Windows Named Pipe support. +//! ## Feature flags //! -//! As of version 0.6, this project now generates API stubs from the upstream Docker-maintained -//! [Swagger OpenAPI specification](https://docs.docker.com/engine/api/v1.41.yaml). The generated -//! models are committed to this repository, but packaged in a separate crate -//! [bollard-stubs](https://crates.io/crates/bollard-stubs). +//! - `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/) is pegged at version `1.41`. The -//! library also supports [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. //! @@ -52,9 +67,8 @@ //! //! ### Socket //! -//! The client will connect to the standard unix socket location `/var/run/docker.sock` or windows -//! named pipe location `//./pipe/docker_engine`. Use the `Docker::connect_with_socket` method API -//! to parameterise the interface. +//! 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; @@ -62,29 +76,34 @@ //! 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. -//! Use the `Docker::connect_with_local` method API to parameterise the interface. +//! //! ```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. Use the -//! `Docker::connect_with_http` method API to -//! parameterise the interface. +//! `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 @@ -94,15 +113,14 @@ //! certificates - `key.pem` for the private key, `cert.pem` for the server certificate and //! `ca.pem` for the certificate authority chain. //! -//! Use the `Docker::connect_with_ssl` method API -//! to parameterise the interface. -//! //! ```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 @@ -194,7 +212,7 @@ //! //! # Development //! -//! Contributions are welcome, please observe the following advice. +//! Contributions are welcome, please observe the following. //! //! ## Building the proto models //!