Crate compose_spec

Expand description

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.

§Fragments

serde_yaml does use YAML anchors and aliases during deserialization. However, it does not automatically merge the YAML merge type (<< keys). You can use serde_yaml::Value::apply_merge() to merge << keys into the surrounding mapping. Options::apply_merge() is available to do this for you.

use compose_spec::Compose;

let yaml = "\
services:
  one:
    environment: &env
      FOO: foo
      BAR: bar
  two:
    environment: *env
  three:
    environment:
      <<: *env
      BAR: baz
";

let compose = Compose::options()
    .apply_merge(true)
    .from_yaml_str(yaml)?;

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.
Options: Deserialization options builder for a Compose file.
ValidationError: Error returned when validation of a Compose file fails.
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.

Crate compose_specCopy item path