3 releases (breaking)
0.3.0 | Oct 16, 2024 |
---|---|
0.2.0 | Apr 24, 2024 |
0.1.0 | Apr 5, 2024 |
#422 in Parser implementations
184 downloads per month
Used in podlet
545KB
11K
SLoC
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
andDuration
.
- Uses semantically appropriate types from the standard library like
- Correctness
- Values are fully validated and parsed.
- Enums are used for fields which conflict with each other. For example, in
services
,network_mode
andnetworks
are combined intonetwork_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
andports
).
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
- Install the nightly Rust toolchain,
- 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
- Install the nightly Rust toolchain,
- 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.
Dependencies
~3.5–5MB
~93K SLoC