ttn.api.discovery.discovery.proto Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of management Show documentation
The Things Network Handler API Client
The newest version!
// Copyright © 2017 The Things Network
// Use of this source code is governed by the MIT license that can be found in the LICENSE file.

syntax = "proto3";

import "google/protobuf/empty.proto";
import "google/api/annotations.proto";

package discovery;

option java_package = "org.thethingsnetwork.management.proto";

option go_package = "github.com/TheThingsNetwork/ttn/api/discovery";

message Metadata {
  oneof metadata {
    // General metadata (0-9)

    // 

    // Metadata for Router component (10-19)

    // 

    // Metadata for Broker component (20-29)

    // DevAddr prefix that is routed by this Broker
    // 5 bytes; the first byte is the prefix length, the following 4 bytes are the address.
    // Only authorized Brokers can announce PREFIX metadata.
    bytes dev_addr_prefix = 20; // for some reason gogoproto customtype doesn't work in a oneof, so we do this manually

    // Metadata for Handler component (30-39)

    // AppID that is registered to this Handler
    // This metadata can only be added if the requesting client is authorized to manage this AppID.
    string app_id = 30;

    // AppEUI that is registered to this Join Handler
    // Only authorized Join Handlers can announce APP_EUI metadata (and we don't have any of those yet).
    bytes app_eui = 31; // for some reason gogoproto customtype doesn't work in a oneof, so we do this manually
  }
}

// The Announcement of a service (also called component)
message Announcement {
  // The ID of the component
  string id = 1;

  // The name of the component (router/broker/handler)
  string service_name = 2;

  // Service version in the form "[version]-[commit] ([build date])"
  string service_version = 3;

  // Description of the component
  string description = 4;

  // URL with documentation or more information about this component
  string url         = 5;

  // Indicates whether this service is part of The Things Network (the public community network)
  bool   public      = 6;

  // Comma-separated network addresses in the form "domain1:port,domain2:port,domain3:port" (currently we only use the first)
  string net_address = 11;

  // ECDSA public key of this component
  string public_key  = 12;

  // TLS Certificate for gRPC on net_address (if TLS is enabled)
  string certificate = 13;

  // Contains the address where the HTTP API is exposed (if there is one).
  // Format of api_address: `http(s)://domain(:port)`
  // default http port is 80, default https port is 443.
  string api_address = 14;
  // Contains the address where the MQTT API is exposed (if there is one)
  // Format of mqtt_address: `(mqtt(s)://)host(:port)`
  // default mqtt port is 1883, default mqtts port is 8883.
  // Examples:
  // if `host:port` then `mqtt://host:port`
  // if `host:8883` then `mqtts://host:8883`
  // if `host` then `mqtt://host:1883` and `mqtts://host:8883`
  // if `mqtt://host` then `mqtt://host:1883`
  // if `mqtts://host` then `mqtt://host:1883` and `mqtts://host:8883`
  string mqtt_address = 15;
  // Contains the address where the AMQP API is exposed (if there is one)
  // Format of amqp_address: `(amqp(s)://)host(:port)`
  // default amqp port is 5672, default amqps port is 5671.
  // Examples:
  // if `host:port` then `amqp://host:port`
  // if `host:5671` then `amqps://host:5671`
  // if `host` then `amqp://host:5672` and `amqps://host:5671`
  // if `amqp://host` then `amqp://host:5672`
  // if `amqps://host` then `amqp://host:5672` and `amqps://host:5671`
  string amqp_address = 16;

  // Metadata for this component
  repeated Metadata metadata = 22;
}

message GetServiceRequest {
  // The name of the service (router/broker/handler)
  string service_name = 1;
}

// The identifier of the service that should be returned
message GetRequest {
  // The ID of the service
  string id = 1;

  // The name of the service (router/broker/handler)
  string service_name = 2;
}

// The metadata to add or remove from an announement
message MetadataRequest {
  // The ID of the service that should be modified
  string id = 1;

  // The name of the service (router/broker/handler) that should be modified
  string service_name = 2;

  // Metadata to add or remove
  Metadata metadata = 12;
}

// A list of announcements
message AnnouncementsResponse {
  repeated Announcement services = 1;
}

// The Discovery service is used to discover services within The Things Network.
service Discovery {
  // Announce a component to the Discovery server.
  // A call to `Announce` does not processes the `metadata` field, so you can safely leave this field empty.
  // Adding or removing Metadata should be done with the `AddMetadata` and `DeleteMetadata` methods.
  rpc Announce(Announcement) returns (google.protobuf.Empty);

  // Get all announcements for a specific service type
  rpc GetAll(GetServiceRequest) returns (AnnouncementsResponse) {
    option (google.api.http) = {
      get: "/announcements/{service_name}"
    };
  }

  // Get a specific announcement
  rpc Get(GetRequest) returns (Announcement)  {
    option (google.api.http) = {
      get: "/announcements/{service_name}/{id}"
    };
  }

  // Add metadata to an announement
  rpc AddMetadata(MetadataRequest) returns (google.protobuf.Empty);

  // Delete metadata from an announcement
  rpc DeleteMetadata(MetadataRequest) returns (google.protobuf.Empty);
}

// The DiscoveryManager service provides configuration and monitoring functionality
service DiscoveryManager {

}