vpn.proto

syntax = "proto3";
option go_package = "github.com/coder/coder/v2/vpn";
option csharp_namespace = "Coder.Desktop.Vpn.Proto";

import "google/protobuf/timestamp.proto";

package vpn;

// The CoderVPN protocol operates over a bidirectional stream between a "manager" and a "tunnel."
// The manager is part of the Coder Desktop application and written in OS native code. It handles
// configuring the VPN and displaying status to the end user.  The tunnel is written in Go and
// handles operating the actual tunnel, including reading and writing packets, & communicating with
// the Coder server control plane.


// RPC allows a very simple unary request/response RPC mechanism.  The requester generates a unique
// msg_id which it sets on the request, the responder sets response_to that msg_id on the response
// message
message RPC {
    uint64 msg_id = 1;
    uint64 response_to = 2;
}

// ManagerMessage is a message from the manager (to the tunnel).
message ManagerMessage {
    RPC rpc = 1;
    oneof msg {
        GetPeerUpdate get_peer_update = 2;
        NetworkSettingsResponse network_settings = 3;
        StartRequest start = 4;
        StopRequest stop = 5;
    }
}

// TunnelMessage is a message from the tunnel (to the manager).
message TunnelMessage {
    RPC rpc = 1;
    oneof msg {
        Log log = 2;
        PeerUpdate peer_update = 3;
        NetworkSettingsRequest network_settings = 4;
        StartResponse start = 5;
        StopResponse stop = 6;
    }
}

// Log is a log message generated by the tunnel.  The manager should log it to the system log. It is
// one-way tunnel -> manager with no response.
message Log {
    enum Level {
        // these are designed to match slog levels
        DEBUG = 0;
        INFO = 1;
        WARN = 2;
        ERROR = 3;
        CRITICAL = 4;
        FATAL = 5;
    }
    Level level = 1;

    string message = 2;
    repeated string logger_names = 3;

    message Field {
        string name = 1;
        string value = 2;
    }
    repeated Field fields = 4;
}

// GetPeerUpdate asks for a PeerUpdate with a full set of data.
message GetPeerUpdate {}

// PeerUpdate is an update about workspaces and agents connected via the tunnel. It is generated in
// response to GetPeerUpdate (which dumps the full set). It is also generated on any changes (not in
// response to any request).
message PeerUpdate {
    repeated Workspace upserted_workspaces = 1;
    repeated Agent upserted_agents = 2;
    repeated Workspace deleted_workspaces = 3;
    repeated Agent deleted_agents = 4;
}

message Workspace {
    bytes id = 1; // UUID
    string name = 2;

    enum Status {
        UNKNOWN = 0;
        PENDING = 1;
        STARTING = 2;
        RUNNING = 3;
        STOPPING = 4;
        STOPPED = 5;
        FAILED = 6;
        CANCELING = 7;
        CANCELED = 8;
        DELETING = 9;
        DELETED = 10;
    }
    Status status = 3;
}

message Agent {
    bytes id = 1; // UUID
    string name = 2;
    bytes workspace_id = 3; // UUID
    repeated string fqdn = 4;
    repeated string ip_addrs = 5;
    // last_handshake is the primary indicator of whether we are connected to a peer. Zero value or
    // anything longer than 5 minutes ago means there is a problem.
    google.protobuf.Timestamp last_handshake = 6;
}

// NetworkSettingsRequest is based on
// https://developer.apple.com/documentation/networkextension/nepackettunnelnetworksettings for
// macOS.  It is a request/response message with response NetworkSettingsResponse
message NetworkSettingsRequest {
    uint32 tunnel_overhead_bytes = 1;
    uint32 mtu = 2;

    message DNSSettings {
        repeated string servers = 1;
        repeated string search_domains = 2;
        // domain_name is the primary domain name of the tunnel
        string domain_name = 3;
        repeated string match_domains = 4;
        // match_domains_no_search specifies if the domains in the matchDomains list should not be
        // appended to the resolver’s list of search domains.
        bool match_domains_no_search = 5;
    }
    DNSSettings dns_settings = 3;

    string tunnel_remote_address = 4;

    message IPv4Settings {
        repeated string addrs = 1;
        repeated string subnet_masks = 2;
        // router is the next-hop router in dotted-decimal format
        string router = 3;

        message IPv4Route {
            string destination = 1;
            string mask = 2;
            // router is the next-hop router in dotted-decimal format
            string router = 3;
        }
        repeated IPv4Route included_routes = 4;
        repeated IPv4Route excluded_routes = 5;
    }
    IPv4Settings ipv4_settings = 5;

    message IPv6Settings {
        repeated string addrs = 1;
        repeated uint32 prefix_lengths = 2;

        message IPv6Route {
            string destination = 1;
            uint32 prefix_length = 2;
            // router is the address of the next-hop
            string router = 3;
        }
        repeated IPv6Route included_routes = 3;
        repeated IPv6Route excluded_routes = 4;
    }
    IPv6Settings ipv6_settings = 6;
}

// NetworkSettingsResponse is the response from the manager to the tunnel for a
// NetworkSettingsRequest
message NetworkSettingsResponse {
    bool success = 1;
    string error_message = 2;
}

// StartRequest is a request from the manager to start the tunnel.  The tunnel replies with a
// StartResponse.
message StartRequest {
    int32 tunnel_file_descriptor = 1;
    string coder_url = 2;
    string api_token = 3;
    // Additional HTTP headers added to all requests
    message Header {
        string name = 1;
        string value = 2;
    }
    repeated Header headers = 4;
}

message StartResponse {
    bool success = 1;
    string error_message = 2;
}

// StopRequest is a request from the manager to stop the tunnel. The tunnel replies with a
// StopResponse.
message StopRequest {}

// StopResponse is a response to stopping the tunnel. After sending this response, the tunnel closes
// its side of the bidirectional stream for writing.
message StopResponse {
    bool success = 1;
    string error_message = 2;
}