Example: plugins and the lifecycle

# The configuration the plugin example applies. The docker blocks come from
# the external Docker plugin, the template block from the in-process template
# plugin.
#
# Variables can be overridden with environment variables prefixed XCL_VAR_,
# i.e. XCL_VAR_output_dir.

# output_dir is where the rendered templates are written
variable "output_dir" {
  default = "./build/rendered"
}

# A Docker bridge network named app. The Docker plugin sets the computed
# docker_id when it creates it.
docker "network" "app" {
  subnet = "10.42.0.0/24"
}

# A script the web container runs when it starts. The mode makes it
# executable, which the nginx image needs before it runs a script from its
# entrypoint directory. Editing the source renders the file again and leaves
# the container alone; moving the destination replaces the template, and with
# it the container that mounts the script.
template "init" {
  source = <<-EOF
  #!/bin/sh
  echo "web joined the {{network}} network" > /usr/share/nginx/html/init.txt
  EOF

  destination = "${variable.output_dir}/init.sh"
  mode        = "0755"

  variables = {
    network = docker.network.app.meta.name
  }
}

# An nginx container named web on the app network. Referring to the network
# orders the blocks, web is always created after app and destroyed before it.
# Changing its networks moves the running container in place; changing its
# image, command, environment or init script creates a new one.
docker "container" "web" {
  image = "nginx:1.27-alpine"

  # mounted into the nginx entrypoint directory, run when the container starts
  init_script = template.init.destination

  # a nested block, repeated once per network the container joins
  network {
    name    = docker.network.app.meta.name
    aliases = ["web"]
  }
}

# template has no subtype, so it takes just a name. Its variables read the
# container's ip_address, which the Docker plugin computes when it creates the
# container, so a value crosses from the external plugin to the in-process
# one.
template "welcome" {
  source = <<-EOF
  Welcome to the {{network}} network.
  The web container answers at http://{{address}}/
  EOF

  destination = "${variable.output_dir}/welcome.txt"

  variables = {
    network = docker.network.app.meta.name
    address = docker.container.web.ip_address
  }
}

// Container defines the block type docker "container", a Docker container
// named after the block
type Container struct {
  Meta types.Meta

  // Image is the image the container runs, it is pulled when Docker does
  // not have it
  Image string `xcl:"image" json:"image"`

  // Command overrides the image's command
  Command []string `xcl:"command,optional" json:"command,omitempty"`

  // Environment holds the container's environment variables
  Environment map[string]string `xcl:"environment,optional" json:"environment,omitempty"`

  // InitScript is the path of a script the container runs when it starts,
  // mounted read-only into the nginx image's entrypoint directory. It is
  // usually a template's destination, so replacing that template replaces
  // the container.
  InitScript string `xcl:"init_script,optional" json:"init_script,omitempty"`

  // Networks are the networks the container joins, one nested network block
  // each. The container is created on the first and connected to the rest.
  Networks []NetworkAttachment `xcl:"network,block" json:"network,omitempty"`

  // DockerID is computed, the ID Docker gives the container
  DockerID string `xcl:"docker_id,optional,computed" json:"docker_id,omitempty"`

  // IPAddress is computed, the container's address on its first network
  IPAddress string `xcl:"ip_address,optional,computed" json:"ip_address,omitempty"`
}

// NetworkAttachment is a nested network block of a docker "container" block
type NetworkAttachment struct {
  // Name is the Docker name of the network, i.e. docker.network.app.meta.name
  Name string `xcl:"name" json:"name"`

  // Aliases are extra names the container is known by on the network
  Aliases []string `xcl:"aliases,optional" json:"aliases,omitempty"`
}

// Init builds the Docker client from the environment, and the container task
// layer over it once, then registers both block types, each with a provider
// sharing that task layer. Building them does not contact Docker, the
// providers do when they are called.
//
// logger is plugin scoped, for messages written outside a provider call like
// this one. xcl adds provider=<block subtype> to what each provider's Init
// logs. During a call the providers log through plugins.Logger(ctx) instead,
// which xcl binds to the resource and step being worked on.
func (p *Plugin) Init(logger logger.Logger, state plugins.State) error {
  client, err := dockerclient.New()
  if err != nil {
    return err
  }

  tasks := containers.New(client)

  logger.Debug("registering block types", "block_types", "docker.network, docker.container")

  err = plugins.RegisterResourceProvider(
    &p.PluginBase,
    logger,
    state,
    "docker",
    "network",
    &entities.Network{},
    providers.NewNetworkProvider(tasks),
  )
  if err != nil {
    return err
  }

  return plugins.RegisterResourceProvider(
    &p.PluginBase,
    logger,
    state,
    "docker",
    "container",
    &entities.Container{},
    providers.NewContainerProvider(tasks),
  )
}

// Docker is the part of the Docker Engine SDK client the task layer uses. Each
// method has the same signature as the SDK's, so *client.Client satisfies it.
type Docker interface {
  Ping(ctx context.Context) (types.Ping, error)

  NetworkCreate(ctx context.Context, name string, options network.CreateOptions) (network.CreateResponse, error)
  NetworkInspect(ctx context.Context, networkID string, options network.InspectOptions) (network.Inspect, error)
  NetworkRemove(ctx context.Context, networkID string) error
  NetworkConnect(ctx context.Context, networkID, containerID string, config *network.EndpointSettings) error
  NetworkDisconnect(ctx context.Context, networkID, containerID string, force bool) error

  ImageList(ctx context.Context, options image.ListOptions) ([]image.Summary, error)
  ImagePull(ctx context.Context, ref string, options image.PullOptions) (io.ReadCloser, error)

  ContainerCreate(ctx context.Context, config *container.Config, hostConfig *container.HostConfig, networkingConfig *network.NetworkingConfig, platform *ocispec.Platform, containerName string) (container.CreateResponse, error)
  ContainerStart(ctx context.Context, containerID string, options container.StartOptions) error
  ContainerStop(ctx context.Context, containerID string, options container.StopOptions) error
  ContainerRemove(ctx context.Context, containerID string, options container.RemoveOptions) error
  ContainerInspect(ctx context.Context, containerID string) (container.InspectResponse, error)
}

// the real SDK client satisfies Docker without an adapter
var _ Docker = (*dockerclient.Client)(nil)

// Tasks are the Docker tasks the plugin's providers perform
type Tasks interface {
  // CreateNetwork creates a labelled, attachable bridge network and
  // returns its Docker ID
  CreateNetwork(ctx context.Context, name string, spec NetworkSpec) (string, error)

  // NetworkContainers returns the IDs of the containers attached to the
  // network, sorted
  NetworkContainers(ctx context.Context, networkID string) ([]string, error)

  // RemoveNetwork removes the network
  RemoveNetwork(ctx context.Context, networkID string) error

  // ConnectNetwork attaches the container to the network with aliases
  ConnectNetwork(ctx context.Context, network, containerID string, aliases []string) error

  // DisconnectNetwork force-detaches the container from the network
  DisconnectNetwork(ctx context.Context, network, containerID string) error

  // EnsureImage pulls the image unless Docker already has it
  EnsureImage(ctx context.Context, ref string) error

  // CreateContainer creates the container and returns its Docker ID
  CreateContainer(ctx context.Context, spec ContainerSpec) (string, error)

  // StartContainer starts the container
  StartContainer(ctx context.Context, containerID string) error

  // StopContainer stops the container
  StopContainer(ctx context.Context, containerID string) error

  // RemoveContainer force-removes the container
  RemoveContainer(ctx context.Context, containerID string) error

  // ContainerAddresses returns the container's address on each network it
  // is attached to, keyed by network name
  ContainerAddresses(ctx context.Context, containerID string) (map[string]string, error)
}

// Create asks Docker for a labelled bridge network named after the block, and
// records the ID Docker gives it
func (p *networkProvider) Create(ctx context.Context, n *entities.Network) (*entities.Network, error) {
  id, err := p.tasks.CreateNetwork(ctx, n.Meta.Name, containers.NetworkSpec{
    Subnet: n.Subnet,
    Labels: labels(n.Meta),
  })
  if err != nil {
    return nil, fmt.Errorf("unable to create network %s: %w", n.Meta.Name, err)
  }

  n.DockerID = id
  plugins.Logger(ctx).Info("created network", "name", n.Meta.Name, "id", n.DockerID)

  return n, nil
}

// Destroy removes the network, a network that is already gone counts as
// removed. Every container still attached is force-disconnected first, so
// rebuilding a network never fails on its active endpoints; the container's
// own Update attaches it again to the network that replaces this one.
func (p *networkProvider) Destroy(ctx context.Context, n *entities.Network, force bool) error {
  // sorted, so the containers are always detached in the same order
  attached, err := p.tasks.NetworkContainers(ctx, n.DockerID)
  if errors.Is(err, containers.ErrNotFound) {
    plugins.Logger(ctx).Info("network already removed", "name", n.Meta.Name, "id", n.DockerID)
    return nil
  }

  if err != nil {
    return fmt.Errorf("unable to inspect network %s: %w", n.Meta.Name, err)
  }

  for _, containerID := range attached {
    err := p.tasks.DisconnectNetwork(ctx, n.DockerID, containerID)
    if err != nil && !errors.Is(err, containers.ErrNotFound) {
      return fmt.Errorf("unable to disconnect container %s from network %s: %w", containerID, n.Meta.Name, err)
    }

    plugins.Logger(ctx).Info("disconnected container from network", "name", n.Meta.Name, "container", containerID)
  }

  err = p.tasks.RemoveNetwork(ctx, n.DockerID)
  if err != nil && !errors.Is(err, containers.ErrNotFound) {
    return fmt.Errorf("unable to remove network %s: %w", n.Meta.Name, err)
  }

  plugins.Logger(ctx).Info("destroyed network", "name", n.Meta.Name, "id", n.DockerID)

  return nil
}

// Create pulls the image when Docker does not have it, creates the container
// on its first network, connects the rest, starts it and records its ID and
// its address on the first network. When a step after the container was
// created fails, the container is removed again.
func (p *containerProvider) Create(ctx context.Context, c *entities.Container) (*entities.Container, error) {
  err := p.tasks.EnsureImage(ctx, c.Image)
  if err != nil {
    return nil, err
  }

  spec := containers.ContainerSpec{
    Name:        c.Meta.Name,
    Image:       c.Image,
    Command:     c.Command,
    Environment: c.Environment,
    Labels:      labels(c.Meta),
  }

  if len(c.Networks) > 0 {
    first := c.Networks[0]
    spec.Network = &containers.Attachment{Name: first.Name, Aliases: first.Aliases}
  }

  if c.InitScript != "" {
    path, err := filepath.Abs(c.InitScript)
    if err != nil {
      return nil, fmt.Errorf("unable to mount the init script of container %s: %w", c.Meta.Name, err)
    }

    spec.InitScript = path
  }

  id, err := p.tasks.CreateContainer(ctx, spec)
  if err != nil {
    return nil, fmt.Errorf("unable to create container %s: %w", c.Meta.Name, err)
  }

  address, err := p.startContainer(ctx, c, id)
  if err != nil {
    removeErr := p.tasks.RemoveContainer(ctx, id)
    return nil, errors.Join(err, removeErr)
  }

  c.DockerID = id
  c.IPAddress = address
  plugins.Logger(ctx).Info("created container", "name", c.Meta.Name, "image", c.Image, "ip_address", c.IPAddress)

  return c, nil
}

// initScriptPath is where the init script is mounted. The nginx image's
// entrypoint runs every executable script in /docker-entrypoint.d before it
// starts nginx.
const initScriptPath = "/docker-entrypoint.d/90-xcl-init.sh"

// CreateContainer creates the container on its network, with its environment
// sorted and its init script mounted read-only at initScriptPath
func (t *tasks) CreateContainer(ctx context.Context, spec ContainerSpec) (string, error) {
  config := &container.Config{
    Image:  spec.Image,
    Cmd:    spec.Command,
    Env:    environment(spec.Environment),
    Labels: spec.Labels,
  }

  networking := &network.NetworkingConfig{}
  if spec.Network != nil {
    networking.EndpointsConfig = map[string]*network.EndpointSettings{
      spec.Network.Name: {Aliases: spec.Network.Aliases},
    }
  }

  hostConfig := &container.HostConfig{}
  if spec.InitScript != "" {
    hostConfig.Binds = []string{spec.InitScript + ":" + initScriptPath + ":ro"}
  }

  resp, err := t.client.ContainerCreate(ctx, config, hostConfig, networking, nil, spec.Name)
  if err != nil {
    return "", notFound(err)
  }

  return resp.ID, nil
}

// startContainer connects the created container to its further networks,
// starts it and returns its address on its first network
func (p *containerProvider) startContainer(ctx context.Context, c *entities.Container, id string) (string, error) {
  for _, attachment := range c.Networks[min(1, len(c.Networks)):] {
    err := p.tasks.ConnectNetwork(ctx, attachment.Name, id, attachment.Aliases)
    if err != nil {
      return "", fmt.Errorf("unable to connect container %s to network %s: %w", c.Meta.Name, attachment.Name, err)
    }
  }

  err := p.tasks.StartContainer(ctx, id)
  if err != nil {
    return "", fmt.Errorf("unable to start container %s: %w", c.Meta.Name, err)
  }

  addresses, err := p.tasks.ContainerAddresses(ctx, id)
  if err != nil {
    return "", fmt.Errorf("unable to inspect container %s: %w", c.Meta.Name, err)
  }

  return firstAddress(c, addresses), nil
}

// networkReplaceSettings are the settings Docker fixes when it creates a
// network, a change to any of them needs a new network
var networkReplaceSettings = []entity.Path{
  entity.Path{}.Attribute("subnet"),
}

// Changed decides from what it is told. It answers replace when the subnet
// changed: Docker can not move a network to a new address range, the network
// has to be removed and created again. Any other change to its settings
// answers update, which needs no Docker call. When nothing changed the
// decision is left to DefaultChanged.
func (p *networkProvider) Changed(ctx context.Context, old *entities.Network, new *entities.Network, changes []entity.PropertyChange, dependencies []entity.DependencyChange) (entity.Change, error) {
  for _, change := range changes {
    for _, setting := range networkReplaceSettings {
      if change.Within(setting) {
        return entity.Replace, nil
      }
    }
  }

  if len(changes) > 0 {
    return entity.Update, nil
  }

  return p.DefaultChanged.Changed(ctx, old, new, changes, dependencies)
}

// replaceSettings are the settings Docker fixes when it creates a container,
// a change to any of them needs a new container
var replaceSettings = []entity.Path{
  entity.Path{}.Attribute("image"),
  entity.Path{}.Attribute("command"),
  entity.Path{}.Attribute("environment"),
  entity.Path{}.Attribute("init_script"),
}

// Changed decides from what it is told. It answers replace when the image,
// command, environment or init script changed, since Docker fixes them when
// it creates a container, or when a dependency other than a Docker network is
// replaced, such as the template that renders the init script. A change to
// the container's networks, or a network that is updated or replaced, is
// handled in place by Update, which moves the running container between
// networks. Any other change to its settings answers update. A dependency
// that is only updated, such as the init script's template rendering new
// content, leaves the container alone: the decision is left to
// DefaultChanged.
func (p *containerProvider) Changed(ctx context.Context, old *entities.Container, new *entities.Container, changes []entity.PropertyChange, dependencies []entity.DependencyChange) (entity.Change, error) {
  for _, change := range changes {
    for _, setting := range replaceSettings {
      if change.Within(setting) {
        return entity.Replace, nil
      }
    }
  }

  for _, dependency := range dependencies {
    if dependency.Change == entity.Replace && !isNetworkAddress(dependency.Address) {
      return entity.Replace, nil
    }
  }

  if len(changes) > 0 {
    return entity.Update, nil
  }

  for _, dependency := range dependencies {
    if isNetworkAddress(dependency.Address) {
      return entity.Update, nil
    }
  }

  return p.DefaultChanged.Changed(ctx, old, new, changes, dependencies)
}

// Update moves the running container between networks, working only from what
// it is told, never from what Docker reports:
//
//   - the previous attachments are the configured ones with each network
//     change's previous value put back
//   - networks that went away, or whose aliases changed, are disconnected
//   - networks that are new, or whose aliases changed, are connected
//   - networks that were replaced are connected again, since destroying a
//     network detaches every container
//
// When it moved the container it reads the container's new address, an
// output, not previous state.
func (p *containerProvider) Update(ctx context.Context, c *entities.Container, changes []entity.PropertyChange, dependencies []entity.DependencyChange) (*entities.Container, error) {
  previous, err := previousAttachments(c.Networks, changes)
  if err != nil {
    return nil, fmt.Errorf("unable to work out the previous networks of container %s: %w", c.Meta.Name, err)
  }

  moved := false

  for _, attachment := range previous {
    current, ok := findAttachment(c.Networks, attachment.Name)
    if ok && equalStrings(current.Aliases, attachment.Aliases) {
      continue
    }

    // a network that was removed or rebuilt has already detached it
    err := p.tasks.DisconnectNetwork(ctx, attachment.Name, c.DockerID)
    if err != nil && !errors.Is(err, containers.ErrNotFound) {
      return nil, fmt.Errorf("unable to disconnect container %s from network %s: %w", c.Meta.Name, attachment.Name, err)
    }

    plugins.Logger(ctx).Info("disconnected container from network", "name", c.Meta.Name, "network", attachment.Name)
    moved = true
  }

  connected := map[string]bool{}
  for _, attachment := range c.Networks {
    before, ok := findAttachment(previous, attachment.Name)
    if ok && equalStrings(before.Aliases, attachment.Aliases) {
      continue
    }

    if err := p.connect(ctx, c, attachment); err != nil {
      return nil, err
    }

    connected[attachment.Name] = true
    moved = true
  }

  for _, dependency := range dependencies {
    if dependency.Change != entity.Replace || !isNetworkAddress(dependency.Address) {
      continue
    }

    attachment, ok := findAttachment(c.Networks, networkName(dependency.Address))
    if !ok || connected[attachment.Name] {
      continue
    }

    if err := p.connect(ctx, c, attachment); err != nil {
      return nil, err
    }

    connected[attachment.Name] = true
    moved = true
  }

  if !moved {
    return c, nil
  }

  addresses, err := p.tasks.ContainerAddresses(ctx, c.DockerID)
  if err != nil {
    return nil, fmt.Errorf("unable to inspect container %s: %w", c.Meta.Name, err)
  }

  c.IPAddress = firstAddress(c, addresses)

  return c, nil
}

// main serves the plugin to the host that started this process
func main() {
  plugins.Serve(&docker.Plugin{})
}

// Init registers template with no subtype, so a block is written
// template "<name>" {} and addressed template.<name>
func (p *TemplatePlugin) Init(logger logger.Logger, state plugins.State) error {
  logger.Debug("registering block types", "block_types", "template")

  return plugins.RegisterResourceProvider(
    &p.PluginBase,
    logger,
    state,
    "template",
    "",
    &Template{},
    &provider{},
  )
}

// Create renders the template with its variables and writes the result to the
// destination
func (p *provider) Create(ctx context.Context, t *Template) (*Template, error) {
  err := render(t)
  if err != nil {
    return nil, err
  }

  plugins.Logger(ctx).Info("rendered template", "destination", t.Destination)

  return t, nil
}

// Changed answers replace when the destination changes: Update renders to the
// new path but would leave the file at the old one behind, so the template is
// destroyed, removing its file, and created again. A change to the source or
// variables is left to DefaultChanged, which answers update, and Update
// renders the file again.
func (p *provider) Changed(ctx context.Context, old *Template, new *Template, changes []entity.PropertyChange, dependencies []entity.DependencyChange) (entity.Change, error) {
  if old.Destination != new.Destination {
    return entity.Replace, nil
  }

  return p.DefaultChanged.Changed(ctx, old, new, changes, dependencies)
}

// render renders t's source with its variables and writes it to its
// destination with its mode, creating the destination's parent directories
func render(t *Template) error {
  mode, err := fileMode(t.Mode)
  if err != nil {
    return err
  }

  tmpl, err := raymond.Parse(t.Source)
  if err != nil {
    return fmt.Errorf("unable to parse template: %w", err)
  }

  // the helpers are the ones xcl's template function offers. They return
  // SafeString because Handlebars HTML-escapes what a helper returns
  // otherwise, which would write " for the quotes quote adds.
  tmpl.RegisterHelpers(map[string]any{
    "quote": func(in string) raymond.SafeString {
      return raymond.SafeString(fmt.Sprintf(`"%s"`, in))
    },
    "trim": func(in string) raymond.SafeString {
      return raymond.SafeString(strings.TrimSpace(in))
    },
  })

  out, err := tmpl.Exec(t.Variables)
  if err != nil {
    return fmt.Errorf("unable to render template: %w", err)
  }

  err = os.MkdirAll(filepath.Dir(t.Destination), 0755)
  if err != nil {
    return fmt.Errorf("unable to create the directory for %s: %w", t.Destination, err)
  }

  err = os.WriteFile(t.Destination, []byte(out), mode)
  if err != nil {
    return fmt.Errorf("unable to write %s: %w", t.Destination, err)
  }

  // WriteFile only sets the mode of a file it creates, a file rendered
  // before keeps its old mode otherwise
  err = os.Chmod(t.Destination, mode)
  if err != nil {
    return fmt.Errorf("unable to set the mode of %s: %w", t.Destination, err)
  }

  return nil
}

// Template defines the block type template, a Handlebars template rendered to
// a file
type Template struct {
  // Meta is the block's metadata, which the status view reads
  Meta types.Meta

  // Source is the Handlebars template text, use file() to read it from a
  // file
  Source string `xcl:"source" json:"source"`

  // Destination is the path of the file the template is rendered to, its
  // parent directories are created when they do not exist
  Destination string `xcl:"destination" json:"destination"`

  // Variables are the values the template refers to, i.e. {{address}}
  Variables map[string]string `xcl:"variables,optional" json:"variables,omitempty"`

  // Mode is the rendered file's permissions as an octal string, i.e.
  // "0755" for a script that is run. It defaults to "0644".
  Mode string `xcl:"mode,optional" json:"mode,omitempty"`
}

template "init" {
  source = <<-EOF
  #!/bin/sh
  echo "web joined the {{network}} network" > /usr/share/nginx/html/init.txt
  EOF

  destination = "${variable.output_dir}/init.sh"
  mode        = "0755"

  variables = {
    network = docker.network.app.meta.name
  }
}

docker "container" "web" {
  image = "nginx:1.27-alpine"

  # mounted into the nginx entrypoint directory, run when the container starts
  init_script = template.init.destination

  ...
}

func TestNetworkCreateFillsTheDockerID(t *testing.T) {
  tasks := mocks.NewMockTasks(t)
  tasks.EXPECT().
    CreateNetwork(context.Background(), "app", containers.NetworkSpec{
      Labels: networkTestLabels(),
    }).
    Return("net-123", nil).
    Once()

  provider := &networkProvider{tasks: tasks}

  created, err := provider.Create(context.Background(), networkTestNetwork())

  require.NoError(t, err)
  require.Equal(t, "net-123", created.DockerID)
}

// requireDocker skips the test when no Docker engine is reachable
func requireDocker(t *testing.T) {
  t.Helper()

  if err := docker.Ping(context.Background()); err != nil {
    t.Skip(err.Error()) // Ping already says no Docker engine is reachable
  }
}