docgen/lib/proto/docgen.proto

syntax = "proto3";

package docgen;

option go_package = "proto";

// Top level docgen document.
message Document {

  Overview overview = 1;

  // The groups of related tasks. Required.
  repeated TaskGroup task_groups = 2;

  PortReference port_reference = 3;

  EnvironmentVariableReference environment_variable_reference = 4;

  VolumeReference volume_reference = 5;
}

// The overview section for the container image.
message Overview {

  // High level description of the image. Required.
  string description = 1;

  // URL to the Dockerfile, typically a github link. Required.
  string dockerfile_url = 2;

  // The image pull command. Required.
  string pull_command = 3;

  repeated AlternativeVersion other_versions = 4;
}

message AlternativeVersion {
  // Short title describing the version. No newlines. Required.
  string title = 1;

  // Description for this version.
  string description = 2;

  // URL to the Dockerfile, typically a github link. Required.
  string dockerfile_url = 3;

  // Documentation URL.
  string documentation_url = 4;
}

// Defines a group of related tasks, which will be put into a
// corresponding common section.
message TaskGroup {

  // Title of this task group. No newlines. Required.
  string title = 1;

  // Overall description for this group of tasks.
  string description = 2;

  // List of tasks. At least 1 required.
  repeated Task tasks = 3;

  // Optionally specifies a link anchor ID. This ID must be unique
  // in the entire document. If not specified, this ID is generated
  // automatically based on the title.
  // Should you want to link to a task group, an explicit ID should
  // be specified here. The link can then be constructed using syntax
  // [](#anchor_id). To force referencing a specific runtime, use
  // [](#anchor_id|DOCKER) or [](#anchor_id|KUBERNETES).
  string anchor_id = 4;
}

// Runtime environment to target.
enum Runtime {
  // docker and docker-compose.
  DOCKER = 0;

  // Kubernetes.
  KUBERNETES = 1;
}

// Captures a task that the user can carry out for this solution.
message Task {

  // The runtime environments to target for this task. Required.
  repeated Runtime runtimes = 1;

  // Title of the task. No newlines. Required.
  string title = 2;

  // Overall description for the task.
  string description = 3;

  // Sequence of instructions to follow to accomplish the task.
  // At least 1 required.
  repeated TaskInstruction instructions = 4;

  // Optionally specifies a link anchor ID. This ID must be unique
  // in the entire document. If not specified, this ID is generated
  // automatically based on the title.
  // Should you want to link to a task group, an explicit ID should
  // be specified here. The link can then be constructed using syntax
  // [](#anchor_id). To force referencing a specific runtime, use
  // [](#anchor_id|DOCKER) or [](#anchor_id|KUBERNETES).
  string anchor_id = 5;
}

message TaskInstruction {
  // Description of this instruction. Required if a more specific
  // instruction type below is not specified.
  string description = 1;

  // Optionally restricts this instruction to only a subset of runtimes
  // supported by the task.
  repeated Runtime applicable_runtimes = 2;

  // Optionally specifies a more specific instruction type.
  // Without one of these specific types, the description is required.
  oneof instruction {
    RunInstruction run = 3;
    DockerfileInstruction dockerfile = 4;
    ExecInstruction exec = 5;
    CopyInstruction copy = 6;
  }
}

// Defines instruction on crafting and building Dockerfile
// to extend an image.
message DockerfileInstruction {
  // The image that appears in the FROM line. Required.
  string base_image = 1;

  // The name of the image resulting from building this Dockerfile.
  // If not specified, the name is generated by prefixing the base image
  // name with "my-". Only the part after the last forward slash in the
  // base image name is used.
  string target_image = 2;

  // Content of the Dockerfile, except for the FROM line.
  string content = 3;
}

// Defines instruction on running a container image.
message RunInstruction {

  // Defines the life of the running container.
  enum RunType {
    // The container is long running, e.g. to provide a service.
    LONG_RUNNING = 0;
    // The container runs as a one-time job. The output is
    // streamed back.
    ONESHOT = 1;
    // Runs the container, connects the shell to its stdin for
    // interactivity, and terminates it when the connection is closed.
    INTERACTIVE_SHELL = 3;
  }

  // Specifies value for an environment variable.
  message EnvironmentVariableValue {
    // Default value for all runtime targets.
    string value = 1;
    // Value for docker, overriding the default value if it exists.
    string docker_value = 2;
    // Value for docker-compose, overriding the default value if it exists.
    string docker_compose_value = 3;
    // Value for kubernetes, overriding the default value if it exists.
    string kubernetes_value = 4;
  }

  message ExposedPort {
    enum Protocol {
      TCP = 0;
      UDP = 1;
    }

    // The network protocol. Required.
    Protocol protocol = 1;

    // The exposed port number. Required.
    int32 port = 2;

    // Maps the exposed port under a different port on the host.
    int32 mapped = 3;
  }

  message MountedVolume {

    // The mounted volume is intended to be a persistent storage
    // that should be initialized to empty.
    message EmptyPersistentVolume {
      // Specifies a path on the localhost that should host this volume.
      // If not specified, it will be derived from the volume name.
      // Applicable for DOCKER and DOCKER_COMPOSE runtimes.
      string host_path = 1;

      // Specifies sub-path for auto-provisioned Kubernetes persistent volume.
      // Auto-provisioned volumes are sometimes not entirely empty, for example
      // they can contain a "lost+found" directory at root, which might not
      // satisfy some application. A sub-path must be a relative path.
      string sub_path = 2;
    }

    // Mounts a single file (not a directory) at the target container path.
    // The host_file's file name will be used on the container as well.
    // Note that the target path in this case points at the containing
    // directory on the container.
    message SingleFile {
      // The location of the file on the host. This should be an absolute
      // path, or "$(pwd)/" is automatically prepended.
      // Required.
      string host_file = 1;
    }

    // A short descriptive name for this volume.
    // Only alphanumeric characters, dashes, and spaces.
    // Must be unique among the volumes across the main and
    // dependent services. Required.
    string name = 1;

    // Filesystem path on the container to mount the volume at.
    // Must be a directory. Required.
    string path = 2;

    oneof source {
      EmptyPersistentVolume empty_persistent_volume = 3;
      SingleFile single_file = 4;
    }
  }

  // Defines a service that is needed by the container.
  message Dependency {
    // Name of the service. The name also serves as the default
    // for some other options. Must be different from the main
    // servce name. Required.
    string name = 1;

    // Defines what docker image to use. Required if the target runtimes
    // include one that supports composite deployments like docker-compose
    // or kubernetes.
    string image = 2;

    // Maps environment variable names to their values.
    map<string, EnvironmentVariableValue> environment = 3;

    repeated MountedVolume volumes = 4;

    // Defines the link alias expected by the main service.
    // Only needed if it's different from "name".
    string docker_link_alias = 5;
  }

  // Defines the life of the running container. Required.
  RunType run_type = 1;

  // Defines the main service name. Required.
  string name = 2;

  // Defines what docker image to use. Required.
  string image = 3;

  // Maps environment variable names to their values.
  map<string, EnvironmentVariableValue> environment = 4;

  repeated ExposedPort exposed_ports = 5;

  repeated MountedVolume volumes = 6;

  // Optionally customizes the command to run.
  // The naming of this field follows convention of Kubernetes,
  // and thus is equivalent to Docker's CMD.
  repeated string arguments = 7;

  // Declares dependencies that this container needs.
  // For a target runtime that supports composite deployments, like
  // docker-compose or kubernetes, the dependencies will be deployed as well.
  repeated Dependency dependencies = 8;
}

// Defines instruction to execute a command within a running container.
message ExecInstruction {

  // Defines how to execute the desired command.
  enum ExecType {
    // Executes the desired command once and exit.
    ONESHOT = 0;
    // Executes the desired command in an interactive shell session.
    INTERACTIVE_SHELL = 1;
  }

  // Defines a command to run, potentially as part of a sequence,
  // after entering an interactive exec session.
  message Subcommand {
    // Optional description for this command.
    string description = 1;

    // The command to run.
    string command = 2;
  }

  ExecType exec_type = 1;

  // Name of the container to exec within. Required.
  oneof container_name_oneof {
    // Specifies the container name directly.
    string container_name = 2;
    // Gets the container name from the run instruction.
    RunInstruction container_from_run = 6;
  }

  // Full exec command. Required.
  string command = 3;

  // A sequence of commands to run after entering an interactive exec session.
  // Optional and only applicable in INTERACTIVE_SHELL exec type.
  repeated Subcommand subcommands = 4;

  // A file name on the host to redirect the stdout to. Optional and only
  // applicable in ONESHOT exec type.
  string redirect_output_to = 5;
}

// Defines instruction to copy files from or to a running container.
message CopyInstruction {

  enum Direction {
    FROM_CONTAINER = 0;
    TO_CONTAINER = 1;
  }
  // Direction of the copy. Required.
  Direction direction = 1;

  // Path on the running container. Required.
  string path = 2;

  // Path on the local host. Required.
  string host_path = 3;

  // Name of the running container to copy from. Required.
  oneof container_name_oneof {
    // Name of the running container.
    string container_name = 4;
    // Gets the container name from a Run instruction.
    RunInstruction container_from_run = 5;
  }
}

// Defines the port reference section.
message PortReference {

  message PortInfo {
    enum Protocol {
      TCP = 0;
      UDP = 1;
    }

    // Network protocol. Required.
    Protocol protocol = 1;

    // Port number of a range of ports. No newlines. Required.
    string port = 2;

    // Description of the exposed port. No newlines. Required.
    string description = 3;
  }

  repeated PortInfo ports = 1;
}

// Defines the environment variable reference section.
message EnvironmentVariableReference {

  message EnvironmentVariableInfo {
    // Name of the environment variable. No newlines. Required.
    string name = 1;

    // Description of the variable. No newlines. Required.
    string description = 2;
  }

  repeated EnvironmentVariableInfo variables = 1;
}

// Defines the volume reference section.
message VolumeReference {
  message VolumeInfo {
    // Container path. No newlines. Required.
    string path = 1;

    // Description of what kind of data stored here. No newlines. Required.
    string description = 2;
  }

  repeated VolumeInfo volumes = 1;
}