arcbox-protocol 0.9.0

Protocol definitions for ArcBox (ttrpc/protobuf)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108

// Common types used across ArcBox protocols.
//
// This file defines shared message types that are used by multiple services.
//
// Design sources:
// - internal-docs/architecture/cli-api.md (ArcBox internal design)
// - Docker Engine API v1.43 (https://docs.docker.com/engine/api/v1.43/)
// - containerd ttrpc protocol design patterns

syntax = "proto3";

package arcbox.v1;

// Empty message for requests/responses that don't need data.
message Empty {}

// Timestamp with nanosecond precision.
message Timestamp {
    // Seconds since Unix epoch.
    int64 seconds = 1;
    // Nanoseconds within the second.
    int32 nanos = 2;
}

// Key-value pair for labels, environment variables, etc.
message KeyValue {
    string key = 1;
    string value = 2;
}

// Mount specification for bind mounts and volumes.
message Mount {
    // Source path on host.
    string source = 1;
    // Target path in container.
    string target = 2;
    // Mount type: bind, volume, tmpfs.
    string type = 3;
    // Read-only flag.
    bool readonly = 4;
}

// Port binding specification.
message PortBinding {
    // Port inside the container.
    uint32 container_port = 1;
    // Port on the host.
    uint32 host_port = 2;
    // Protocol: tcp, udp.
    string protocol = 3;
    // Host IP to bind to.
    string host_ip = 4;
}

// Resource limits for containers.
message ResourceLimits {
    // Memory limit in bytes.
    uint64 memory_bytes = 1;
    // CPU shares (relative weight).
    uint64 cpu_shares = 2;
    // CPU quota in microseconds per period.
    int64 cpu_quota = 3;
    // CPU period in microseconds.
    uint64 cpu_period = 4;
    // Number of CPUs.
    double cpus = 5;
    // Memory swap limit in bytes.
    int64 memory_swap = 6;
}

// An observation of the System VM's persistent storage. Absence means the
// peer does not report storage health, or the current guest is not observable.
// This message does not report daemon liveness or change startup readiness.
message StorageHealth {
    repeated StorageVolumeHealth volumes = 1;
    // Guest wall-clock observation time. Zero means the clock is not available.
    uint64 observed_at_unix_ms = 2;
}

// Mount availability and mode for one persistent System VM volume.
message StorageVolumeHealth {
    enum Role {
        ROLE_UNSPECIFIED = 0;
        DATA = 1;
        METADATA = 2;
    }
    enum State {
        // Observation failed or the peer sent a state the reader does not know.
        STATE_UNSPECIFIED = 0;
        // The expected filesystem is mounted read-write. This is not a
        // successful write/fsync test or a guarantee that future I/O succeeds.
        MOUNTED_READ_WRITE = 1;
        // The expected filesystem is mounted read-only. The mode alone does
        // not identify whether the kernel forced it read-only after an error.
        READ_ONLY = 2;
        // A configured volume is missing, unmounted, or mounted incorrectly.
        UNAVAILABLE = 3;
        // The optional metadata volume is absent from this guest's layout.
        NOT_CONFIGURED = 4;
    }
    Role role = 1;
    State state = 2;
    string device = 3;
    string mount_point = 4;
    string filesystem = 5;
    // Observation error or explanation. Never parse this field for state.
    string detail = 6;
}