README.md

compose_spec

compose_spec is a Rust library crate for (de)serializing from/to the Compose specification.

compose_spec strives for:

• Idiomatic Rust 🦀
  • Uses semantically appropriate types from the standard library like PathBuf and Duration.
• Correctness
  • Values are fully validated and parsed.
  • Enums are used for fields which conflict with each other. For example, in services, network_mode and networks are combined into network_config.
• Ease of use
  • Fully documented, though the documentation could be fleshed out more with examples and explanations, help in this regard would be appreciated!
  • Helpful functions such as conversion between short and long syntax forms of values with multiple representations (e.g. build and ports).

See the documentation for more details.

Examples

use compose_spec::{Compose, Service, service::Image};

let yaml = "\
services:
  caddy:
    image: docker.io/library/caddy:latest
    ports:
      - 8000:80
      - 8443:443
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy-data:/data
volumes:
  caddy-data:
";

// Deserialize `Compose`
let compose: Compose = serde_yaml::from_str(yaml)?;

// Serialize `Compose`
let value = serde_yaml::to_value(&compose)?;

// Get the `Image` of the "caddy" service
let caddy: Option<&Service> = compose.services.get("caddy");
let image: &Option<Image> = &caddy.unwrap().image;
let image: &Image = image.as_ref().unwrap();

assert_eq!(image, "docker.io/library/caddy:latest");
assert_eq!(image.name(), "docker.io/library/caddy");
assert_eq!(image.tag(), Some("latest"));

Minimum Supported Rust Version (MSRV)

The minimum version of the Rust compiler compose_spec can currently compile with is 1.70, which is tested in CI. Increasing the MSRV is not considered to be a breaking change.

Contribution

Contributions, suggestions, and/or comments are appreciated! Feel free to create an issue, discussion, or pull request. Generally, it is preferable to start a discussion for a feature request or open an issue for reporting a bug before submitting changes with a pull request.

Project Layout

compose_spec is composed of two packages set up in a Cargo workspace. The root package, compose_spec, is the main library. The other package, compose_spec_macros, located in a directory of the same name, is a procedural macro library used in compose_spec. compose_spec_macros is not designed to be used outside the compose_spec library.

Local CI

If you are submitting code changes in a pull request and would like to run the CI jobs locally, use the following commands:

• format: cargo fmt --check --all
• clippy: cargo clippy --workspace --tests
• test: cargo test --workspace -- --include-ignored
• doc: cargo doc --workspace --document-private-items
• docs-rs:
  • Install the nightly Rust toolchain, rustup toolchain install nightly.
  • Install cargo-docs-rs.
  • cargo docs-rs
• spellcheck:
  • Install typos.
  • typos
• msrv:
  • Install cargo-msrv.
  • cargo msrv verify
• minimal-versions:
  • Install the nightly Rust toolchain, rustup toolchain install nightly.
  • Install cargo-hack.
  • Install cargo-minimal-versions.
  • cargo minimal-versions check --workspace
  • cargo minimal-versions test --workspace
• semver-checks:
  • Install cargo-semver-checks.
  • cargo semver-checks

License

All source code for compose_spec is licensed under the Mozilla Public License v2.0. View the LICENSE file for more information.

The Compose specification itself is licensed under the Apache License v2.0. See that project's LICENSE file for more information.