// Container service protocol definitions.
//
// This service handles container lifecycle operations.
//
// Design sources:
// - internal-docs/architecture/cli-api.md (proto/container.proto section)
// - Docker Engine API v1.43 Containers endpoints
// - containerd's container service interface

syntax = "proto3";

package arcbox.container;

import "common.proto";

// ContainerService manages container lifecycle.
service ContainerService {
    // Creates a new container.
    rpc Create(CreateContainerRequest) returns (CreateContainerResponse);

    // Starts a stopped container.
    rpc Start(StartContainerRequest) returns (arcbox.common.Empty);

    // Stops a running container.
    rpc Stop(StopContainerRequest) returns (arcbox.common.Empty);

    // Kills a container with a signal.
    rpc Kill(KillContainerRequest) returns (arcbox.common.Empty);

    // Removes a container.
    rpc Remove(RemoveContainerRequest) returns (arcbox.common.Empty);

    // Lists containers.
    rpc List(ListContainersRequest) returns (ListContainersResponse);

    // Inspects a container.
    rpc Inspect(InspectContainerRequest) returns (ContainerInfo);

    // Gets container logs.
    rpc Logs(LogsRequest) returns (stream LogEntry);

    // Creates an exec instance.
    rpc ExecCreate(ExecCreateRequest) returns (ExecCreateResponse);

    // Starts an exec instance.
    rpc ExecStart(ExecStartRequest) returns (stream ExecOutput);

    // Attaches to a container.
    rpc Attach(stream AttachInput) returns (stream AttachOutput);

    // Waits for a container to exit.
    rpc Wait(WaitContainerRequest) returns (WaitContainerResponse);
}

// Request to create a container.
message CreateContainerRequest {
    // Container name (optional, auto-generated if empty).
    string name = 1;
    // Image reference.
    string image = 2;
    // Command to run.
    repeated string cmd = 3;
    // Entrypoint override.
    repeated string entrypoint = 4;
    // Environment variables.
    map<string, string> env = 5;
    // Working directory.
    string working_dir = 6;
    // User to run as.
    string user = 7;
    // Mount specifications.
    repeated arcbox.common.Mount mounts = 8;
    // Port bindings.
    repeated arcbox.common.PortBinding ports = 9;
    // Resource limits.
    arcbox.common.ResourceLimits limits = 10;
    // Labels.
    map<string, string> labels = 11;
    // Hostname.
    string hostname = 12;
    // Allocate a TTY.
    bool tty = 13;
    // Keep stdin open.
    bool stdin_open = 14;
    // Network mode.
    string network_mode = 15;
}

// Response to create container.
message CreateContainerResponse {
    // Container ID.
    string id = 1;
    // Warnings during creation.
    repeated string warnings = 2;
}

// Request to start a container.
message StartContainerRequest {
    // Container ID or name.
    string id = 1;
}

// Request to stop a container.
message StopContainerRequest {
    // Container ID or name.
    string id = 1;
    // Timeout in seconds before kill.
    uint32 timeout = 2;
}

// Request to kill a container.
message KillContainerRequest {
    // Container ID or name.
    string id = 1;
    // Signal to send.
    string signal = 2;
}

// Request to remove a container.
message RemoveContainerRequest {
    // Container ID or name.
    string id = 1;
    // Force removal of running container.
    bool force = 2;
    // Remove associated volumes.
    bool volumes = 3;
}

// Request to list containers.
message ListContainersRequest {
    // Show all containers (not just running).
    bool all = 1;
    // Maximum number of containers to return.
    int32 limit = 2;
    // Show sizes.
    bool size = 3;
    // Filters as JSON-encoded map.
    string filters = 4;
}

// Response to list containers.
message ListContainersResponse {
    // List of containers.
    repeated ContainerSummary containers = 1;
}

// Summary information about a container.
message ContainerSummary {
    // Container ID.
    string id = 1;
    // Container names.
    repeated string names = 2;
    // Image name.
    string image = 3;
    // Image ID.
    string image_id = 4;
    // Command.
    string command = 5;
    // Creation timestamp.
    int64 created = 6;
    // State (running, exited, etc.).
    string state = 7;
    // Status string.
    string status = 8;
    // Port bindings.
    repeated arcbox.common.PortBinding ports = 9;
    // Labels.
    map<string, string> labels = 10;
    // Size in bytes (rw layer).
    int64 size_rw = 11;
    // Size of root filesystem.
    int64 size_root_fs = 12;
}

// Request to inspect a container.
message InspectContainerRequest {
    // Container ID or name.
    string id = 1;
    // Include size information.
    bool size = 2;
}

// Detailed container information.
message ContainerInfo {
    // Container ID.
    string id = 1;
    // Container name.
    string name = 2;
    // Creation timestamp.
    arcbox.common.Timestamp created = 3;
    // Path to container command.
    string path = 4;
    // Arguments to command.
    repeated string args = 5;
    // Container state.
    ContainerState state = 6;
    // Image reference.
    string image = 7;
    // Container configuration.
    ContainerConfig config = 8;
    // Network settings.
    NetworkSettings network_settings = 9;
    // Mount points.
    repeated MountPoint mounts = 10;
}

// Container state information.
message ContainerState {
    // Current status.
    string status = 1;
    // Is container running.
    bool running = 2;
    // Is container paused.
    bool paused = 3;
    // Is container restarting.
    bool restarting = 4;
    // Is OOM killed.
    bool oom_killed = 5;
    // Is container dead.
    bool dead = 6;
    // Container PID.
    int32 pid = 7;
    // Exit code.
    int32 exit_code = 8;
    // Error message.
    string error = 9;
    // Start time.
    string started_at = 10;
    // Finish time.
    string finished_at = 11;
}

// Container configuration.
message ContainerConfig {
    // Hostname.
    string hostname = 1;
    // Domain name.
    string domainname = 2;
    // User.
    string user = 3;
    // Working directory.
    string working_dir = 4;
    // Command.
    repeated string cmd = 5;
    // Entrypoint.
    repeated string entrypoint = 6;
    // Environment variables.
    repeated string env = 7;
    // Image.
    string image = 8;
    // Labels.
    map<string, string> labels = 9;
    // TTY allocation.
    bool tty = 10;
    // Open stdin.
    bool open_stdin = 11;
}

// Network settings.
message NetworkSettings {
    // IP address.
    string ip_address = 1;
    // Gateway.
    string gateway = 2;
    // MAC address.
    string mac_address = 3;
    // Network ID.
    string network_id = 4;
}

// Mount point information.
message MountPoint {
    // Mount type.
    string type = 1;
    // Source.
    string source = 2;
    // Destination.
    string destination = 3;
    // Read-only.
    bool rw = 4;
}

// Request for container logs.
message LogsRequest {
    // Container ID or name.
    string container_id = 1;
    // Follow log output.
    bool follow = 2;
    // Show stdout.
    bool stdout = 3;
    // Show stderr.
    bool stderr = 4;
    // Show timestamps.
    bool timestamps = 5;
    // Only logs since this time (Unix timestamp).
    int64 since = 6;
    // Only logs until this time (Unix timestamp).
    int64 until = 7;
    // Number of lines from end ("all" means all).
    string tail = 8;
}

// Log entry.
message LogEntry {
    // Stream type: stdout or stderr.
    string stream = 1;
    // Log message.
    bytes message = 2;
    // Timestamp.
    arcbox.common.Timestamp timestamp = 3;
}

// Request to create an exec instance.
message ExecCreateRequest {
    // Container ID or name.
    string container_id = 1;
    // Command to run.
    repeated string cmd = 2;
    // Attach stdin.
    bool attach_stdin = 3;
    // Attach stdout.
    bool attach_stdout = 4;
    // Attach stderr.
    bool attach_stderr = 5;
    // Allocate TTY.
    bool tty = 6;
    // Environment variables.
    repeated string env = 7;
    // Working directory.
    string working_dir = 8;
    // User to run as.
    string user = 9;
    // Run in privileged mode.
    bool privileged = 10;
}

// Response to create exec.
message ExecCreateResponse {
    // Exec ID.
    string id = 1;
}

// Request to start an exec instance.
message ExecStartRequest {
    // Exec ID.
    string id = 1;
    // Detach from exec.
    bool detach = 2;
    // TTY mode.
    bool tty = 3;
    // Console size (height, width).
    repeated uint32 console_size = 4;
}

// Exec output.
message ExecOutput {
    // Stream type: stdout or stderr.
    string stream = 1;
    // Output data.
    bytes data = 2;
}

// Attach input.
message AttachInput {
    // Input data.
    bytes data = 1;
    // Resize terminal.
    bool resize = 2;
    // Terminal height.
    uint32 height = 3;
    // Terminal width.
    uint32 width = 4;
}

// Attach output.
message AttachOutput {
    // Stream type.
    string stream = 1;
    // Output data.
    bytes data = 2;
}

// Request to wait for a container.
message WaitContainerRequest {
    // Container ID or name.
    string id = 1;
    // Condition to wait for: not-running, next-exit, removed.
    string condition = 2;
}

// Response when container exits.
message WaitContainerResponse {
    // Exit code.
    int64 status_code = 1;
    // Error message if any.
    string error = 2;
}
