switchboard.proto

// Copyright (c) 2017 Nuxi, https://nuxi.nl/
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions
// are met:
// 1. Redistributions of source code must retain the above copyright
//    notice, this list of conditions and the following disclaimer.
// 2. Redistributions in binary form must reproduce the above copyright
//    notice, this list of conditions and the following disclaimer in the
//    documentation and/or other materials provided with the distribution.
//
// THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
// ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
// ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
// FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
// DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
// OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
// HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
// LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
// OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
// SUCH DAMAGE.

syntax = 'proto3';

package flower.protocol.switchboard;

service Switchboard {
  // Creates a new switchboard connection that is at least as
  // restrictive as the current connection.
  rpc Constrain(ConstrainRequest) returns (ConstrainResponse);

  // Connects a client to a server or an egress.
  rpc ClientConnect(ClientConnectRequest) returns (ClientConnectResponse);

  // Registers and starts an egress. Egresses may only receive
  // connection requests from clients. They may not receive connection
  // requests from ingresses, as both parties would end up providing a
  // socket.
  rpc EgressStart(EgressStartRequest) returns (EgressStartResponse);

  // Connects an ingress to a server. They may not connect to egresses,
  // as both parties would end up providing a socket.
  rpc IngressConnect(IngressConnectRequest) returns (IngressConnectResponse);

  // TODO(ed): Make this complete.
  rpc ResolverStart(ResolverStartRequest) returns (ResolverStartResponse);

  // Registers and starts a server.
  rpc ServerStart(ServerStartRequest) returns (ServerStartResponse);

  // Returns a listing of all servers, egresses and resolvers.
  rpc List(ListRequest) returns (stream ListResponse);
}

// RPCs allowed to be performed on a switchboard connection.
enum Right {
  CLIENT_CONNECT = 0;
  EGRESS_START = 1;
  INGRESS_CONNECT = 2;
  RESOLVER_START = 3;
  SERVER_START = 4;
  LIST = 5;
}

message ConstrainRequest {
  // Actions that are permitted to be performed on the new constrained
  // switchboard connection. These rights must be a subset of the rights
  // present on the existing switchboard connection.
  repeated Right rights = 1;

  // Labels that must be present on any incoming requests for them to be
  // received on the new switchboard connection. This affects
  // EgressStart(), ResolverStart() and ServerStart().
  map<string, string> in_labels = 2;

  // Labels that are automatically added to any outgoing requests. This
  // affects ClientConnect() and IngressConnect().
  map<string, string> out_labels = 3;
}

message ConstrainResponse {
  // A new switchboard connection, having the requested constraints in
  // place.
  fd switchboard = 1;
}

message ClientConnectRequest {
  // Additional labels that should be attached to the connection.
  map<string, string> out_labels = 1;
}

message ClientConnectResponse {
  // Socket file descriptor that provides a stream to the server.
  fd server = 1;

  // Union of the labels provided by the client and server.
  map<string, string> connection_labels = 2;
}

message EgressStartRequest {
  // Additional labels that should be attached to connections.
  map<string, string> in_labels = 1;
}

message EgressStartResponse {
  // A new RPC channel to which the switchboard will send connection
  // requests for every matching connection attempt it receives.
  fd egress = 1;
}

message IngressConnectRequest {
  // Socket file descriptor of an incoming connection that should be
  // passed to a server listening on the switchboard.
  fd client = 1;

  // Additional labels that should be attached to the connection.
  map<string, string> out_labels = 2;
}

message IngressConnectResponse {
  // Union of the labels provided by the client and server.
  map<string, string> connection_labels = 1;
}

message ResolverStartRequest {
  repeated string resolve_labels = 1;
  map<string, string> in_labels = 2;
  map<string, string> out_labels = 3;
}

message ResolverStartResponse {
  fd resolver = 1;
}

message ServerStartRequest {
  // Additional labels that should be attached to connections.
  map<string, string> in_labels = 2;
}

message ServerStartResponse {
  // A new RPC channel to which the switchboard will send connection
  // requests for every matching connection attempt it receives.
  fd server = 1;
}

message ListRequest {
  // Additional labels that should be attached when filtering.
  map<string, string> out_labels = 3;
}

message ListResponse {
  // Labels of a registered egress or server.
  map<string, string> labels = 1;
}