voltha/protos/voltha.proto

syntax = "proto3";

package voltha;

import "google/api/annotations.proto";
import "openflow_13.proto";

option java_package = "org.opencord.voltha";
option java_outer_classname = "VolthaProtos";
option csharp_namespace = "Opencord.Voltha.Voltha";

message NullMessage {}

// Encode health status of a Voltha instance
message HealthStatus {
    // Health states
    enum HealthState {
        HEALTHY = 0;  // The instance is healthy
        OVERLOADED = 1;  // The instance is overloaded, decrease query rate
        DYING = 2;  // The instance is in a critical condition, do not use it
    }

    // Current state of health of this Voltha instance
    HealthState state = 1;
}

// Health related services
service HealthService {
    // Return current health status of a Voltha instance
    rpc GetHealthStatus(NullMessage) returns (HealthStatus) {
        option (google.api.http) = {
            get: "/health"
        };
    }
}

// (placeholder) Address as example message
message Address {
    string id = 7;  // ID of address record
    string street = 1;  // Street address
    string street2 = 2;  // Apartment, suite, building, etc.
    string street3 = 3;  // Apartment, suite, building, etc.
    string city = 4;  // City
    string state = 5;  // State
    uint32 zip = 6;   // Zip code
}

message Addresses {
    repeated Address addresses = 1;
}

// (placeholder) A more complex message type for testing purposes
message MoreComplex {
    HealthStatus health = 1; // Embedded health status
    int32 foo_counter = 2; // Counting foos
    string name = 3;  // Name of this thing
    repeated MoreComplex children = 4;  // Nested object to test recursion type
    Address address = 5;
}

// (placeholder) Convey an identifier
message ID {
    string id = 1;
}

// Subscriber
message Subscriber {
    string id = 1;
    // TODO add meat here
}

message Subscribers {
    repeated Subscriber items = 1;
}

message LogicalDevice {
    string id = 1;
    uint64 datapath_id = 2;
    openflow_13.ofp_desc desc = 3;
}

message LogicalDevices {
    repeated LogicalDevice items = 1;  // List of logical device identifiers
}

message LogicalPorts {
    repeated openflow_13.ofp_port items = 1;
}

message LogicalDeviceDetails {
    string id = 1;
    uint64 datapath_id = 2;
    openflow_13.ofp_desc desc = 3;
    openflow_13.ofp_switch_features switch_features = 4;
}

message FlowTableUpdate {
    string id = 1; // device id
    openflow_13.ofp_flow_mod flow_mod = 2;
}

message GroupTableUpdate {
    string id = 1; // device id
    openflow_13.ofp_group_mod group_mod = 2;
}

message Flows {
    repeated openflow_13.ofp_flow_stats items = 1;
}

message FlowGroups {
    repeated openflow_13.ofp_group_entry items = 1;
}

message PacketIn {
    string id = 1; // device id
    openflow_13.ofp_packet_in packet_in = 2;
}

message PacketOut {
    string id = 1; // device id
    openflow_13.ofp_packet_out packet_out = 2;
}

service VolthaLogicalLayer {

    // List logical devices owned by this Voltha instance
    rpc ListLogicalDevices(NullMessage) returns(LogicalDevices) {
        option (google.api.http) = {
            get: "/local/devices"
        };
    }

    // Get detailed info on logical device owned by this Voltha instance
    rpc GetLogicalDevice(ID) returns(LogicalDeviceDetails) {
        option (google.api.http) = {
            get: "/local/devices/{id}"
        };
    }

    // List ports of a logical device
    rpc ListLogicalDevicePorts(ID) returns(LogicalPorts) {
        option (google.api.http) = {
            get: "/local/devices/{id}/ports"
        };
    }

    // Update flow table for device
    rpc UpdateFlowTable(FlowTableUpdate) returns(NullMessage) {
        option (google.api.http) = {
            post: "/local/devices/{id}/flows"
            body: "*"
        };
    }

    // List all flows of a logical device
    rpc ListDeviceFlows(ID) returns(Flows) {
        option (google.api.http) = {
            get: "/local/devices/{id}/flows"
        };
    }

    // Update group tabel for device
    rpc UpdateGroupTable(GroupTableUpdate) returns(NullMessage) {
        option (google.api.http) = {
            post: "/local/devices/{id}/groups"
            body: "*"
        };
    }

    // List all flow groups of a logical device
    rpc ListDeviceFlowGroups(ID) returns(FlowGroups) {
        option (google.api.http) = {
            get: "/local/devices/{id}/groups"
        };
    }

    // Stream control packets to the dataplane
    rpc StreamPacketsOut(stream PacketOut) returns(NullMessage) {
        // This does not have an HTTP representation
    }

    // Receive control packet stream
    rpc ReceivePacketsIn(NullMessage) returns(stream PacketIn) {
        // This does not have an HTTP representation
    }

    // Create a subscriber record
    rpc CreateSubscriber(Subscriber) returns (Subscriber) {
        option (google.api.http) = {
            post: "/subscribers"
            body: "*"
        };
    }

    // Return an subscriber by ID
    rpc GetSubscriber(ID) returns (Subscriber) {
        option (google.api.http) = {
            get: "/subscribers/{id}"
        };
    }

    // Update an existing subscriber record by ID
    rpc UpdateSubscriber(Subscriber) returns (Subscriber) {
        option (google.api.http) = {
            patch: "/subscribers/{id}"
            body: "*"
        };
    }

    // Delete a subscriber record by ID
    rpc DeleteSubscriber(ID) returns (NullMessage) {
        option (google.api.http) = {
            delete: "/subscribers/{id}"
        };
    }

    // List subscribers
    rpc ListSubscribers(NullMessage) returns (Subscribers) {
        option (google.api.http) = {
            get: "/subscribers"
        };
    }
}

// (placeholder) This is an example service
service ExampleService {

    // Create an address record
    rpc CreateAddress(Address) returns (Address) {
        option (google.api.http) = {
            post: "/addresses"
            body: "*"
        };
    }

    // Return an address by ID
    rpc GetAddress(ID) returns (Address) {
        option (google.api.http) = {
            get: "/addresses/{id}"
        };
    }

    // Update an existing address record by ID
    rpc UpdateAddress(Address) returns (Address) {
        option (google.api.http) = {
            patch: "/addresses/{id}"
            body: "*"
        };
    }

    // Delete an address record by ID
    rpc DeleteAddress(ID) returns (NullMessage) {
        option (google.api.http) = {
            delete: "/addresses/{id}"
        };
    }

    // Return a bit more complex objects
    rpc ListAddresses(NullMessage) returns (Addresses) {
        option (google.api.http) = {
            get: "/addresses"
        };
    }

}

service OpenFlow {

    /*
     * Hello message handshake, initiated by the client (controller)
     */
    rpc GetHello(openflow_13.ofp_hello)
        returns(openflow_13.ofp_hello) {
        // TODO http option
    }

    /*
     * Echo request / reply, initiated by the client (controller)
     */
    rpc EchoRequest(openflow_13.ofp_header)
        returns(openflow_13.ofp_header) {
        // TODO http option
    }

    /*
     * Experimental (extension) RPC
     */
    rpc ExperimenterRequest(openflow_13.ofp_experimenter_header)
        returns(openflow_13.ofp_experimenter_header) {
        // TODO http option
    }

    /*
     * Get Switch Features
     */
    rpc GetSwitchFeatures(openflow_13.ofp_header)
        returns(openflow_13.ofp_switch_features) {
        // TODO http option
    }

    /*
     * Get Switch Config
     */
    rpc GetSwitchConfig(openflow_13.ofp_header)
        returns(openflow_13.ofp_switch_config) {
        // TODO http option
    }

    /*
     * Set Config
     */
    rpc SetConfig(openflow_13.ofp_switch_config)
        returns(openflow_13.ofp_header) {
        // TODO http option
    }

    /*
     * Receive Packet-In messages
     */
    rpc ReceivePacketInMessages(openflow_13.ofp_header)
        returns(stream openflow_13.ofp_packet_in) {
        // TODO http option
    }

    /*
     * Send Packet-Out messages
     */
    rpc SendPacketOutMessages(openflow_13.ofp_packet_out)
        returns(openflow_13.ofp_header) {
        // TODO http option
    }

    // TODO continue

}

/*
message FlowSwitch {
    string id = 1;
    string name = 2;
    uint64 device_id = 3;
    repeated FlowPort ports = 4;
}

enum PortSpeed {
    // TODO
}

enum PortType {
    // TODO
}

message FlowPort {
    string id = 1;
    string name = 2;
    uint32 number = 3;
    string mac_address = 4;
    PortSpeed speed = 5;
    PortType type = 6;
    string flow_switch_id = 7;
}
*/