Crate compose_spec

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

This library attempts to make interacting with and creating Compose files as idiomatic and correct as possible.

• PathBufs are used for fields which denote a path.
• Enums are used for fields which conflict with each other.
• Values are fully parsed and validated when they have a defined format.
• Lists that must contain unique values use IndexSet, otherwise they are Vecs.
• Strings which represent a span of time are converted to/from Durations, see the duration module.

Note that the Deserialize implementations of many types make use of Deserializer::deserialize_any(). This means that you should only attempt to deserialize them from self-describing formats like YAML or JSON.

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"));

Short or Long Syntax Values

Many values within the Compose specification can be represented in either a short or long syntax. The enum ShortOrLong is used to for these values. Conversion from the Short syntax to the Long syntax is always possible. The AsShort trait is used for Long syntax types which may be represented directly as the Short syntax type if additional options are not set.

Re-exports

• pub use self::config::Config;
• pub use self::network::Network;
• pub use self::secret::Secret;
• pub use self::service::Service;

Modules

• config
  Provides Config for the top-level configs field of a Compose file.
• duration
  Utilities for working with Durations.
• network
  Provides Network for the top-level networks field of a Compose file.
• secret
  Provides Secret for the top-level secrets field of a Compose file.
• service
  Provides Service for the Compose top-level services field.

Structs

• Compose
  The Compose file is a YAML file defining a containers based application.
• ExtensionKey
  Valid extension key string.
• Identifier
  Validated identifier for use as a map key in a Compose file.
• Include
  A Compose sub-project to include.
• MapKey
  Valid map key string.
• Name
  Validated Compose project name.
• Volume
  A named volume which can be reused across multiple Services.

Enums

• InvalidExtensionKeyError
  Error returned when attempting to create a ExtensionKey.
• InvalidIdentifierError
  Error returned when attempting to create a Identifier.
• InvalidMapKeyError
  Error returned when attempting to create a MapKey.
• InvalidNameError
  Error returned when attempting to create a Name.
• ItemOrList
  A single item or a list of unique items.
• ListOrMap
  A list of unique strings or a map with optional single values.
• Number
  A numerical Value.
• ParseNumberError
  Error returned when parsing a Number from a string.
• Resource
  A resource managed either externally or by the compose implementation, e.g. a Network or Volume.
• ShortOrLong
  Wrapper for types which may be represented as a Short or Long syntax.
• StringOrNumber
  A string or number value.
• TryFromNumberError
  Error returned when failing to convert a Number into another type.
• TryFromValueError
  Error returned when attempting to convert Value into another type.
• Value
  A single string, number, or boolean value.
• YamlValue
  Represents any valid YAML value.

Traits

• AsShort
  Trait for types that represent a long syntax which could also be represented in a short syntax.
• AsShortIter
  Trait similar to AsShort except it returns an Iterator instead of a reference.

Type Aliases

• Configs
  Configs allow Services to adapt their behavior without needing to rebuild the container image.
• Extensions
  Extensions can be used to enable experimental features or make a Compose file easier to maintain via anchors and aliases.
• Map
  Map with optional single values.
• Networks
  Named networks which allow for Services to communicate with each other.
• Secrets
  Sensitive data that a Service may be granted access to.
• Volumes
  Named volumes which can be reused across multiple Services.