tap.proto

syntax = "proto3";

package io.linkerd.proxy.tap;

option go_package = "github.com/linkerd/linkerd2-proxy-api/go/tap";

import "google/protobuf/duration.proto";

import "http_types.proto";
import "net.proto";

// A service exposed by proxy instances to setup
service Tap {
  rpc Observe(ObserveRequest) returns (stream TapEvent) {}
}

message ObserveRequest {
  // Limits the number of event keys that will be returned by this tap.
  uint32 limit = 1;

  // Encodes request-matching logic.
  Match match = 2;

  message Match {
    message Seq { repeated Match matches = 1; }

    oneof match {
      Seq all = 1;
      Seq any = 2;
      Match not = 3;

      Tcp source = 4;
      Tcp destination = 5;
      Http http = 6;

      Label destination_label = 7;
      Label route_label = 8;
    }

    message Label {
      string key = 1;
      string value = 2;
    }

    message Tcp {
      oneof match {
        Netmask netmask = 1;

        PortRange ports = 3;
      }

      message Netmask {
        net.IPAddress ip = 1;

        uint32 mask = 2;
      }

      // If either a minimum or maximum is not specified, the range is
      // considered to be over a discrete value.
      message PortRange {
        // Minimum matching port value (inclusive), if specified.
        uint32 min = 1;

        // Maximum matching port value (inclusive), if specified.
        uint32 max = 2;
      }
    }

    message Http {
      oneof match {
        http_types.Scheme scheme = 1;
        http_types.HttpMethod method = 3;
        StringMatch authority = 2;
        StringMatch path = 4;
        // TODO Header        header    = 4;
      }

      message StringMatch {
        oneof match {
          string exact = 1;
          string prefix = 2;
        }
      }
    }
  }

  // Conditionally extracts components from requests and responses to include
  // in tap events
  Extract extract = 3;

  message Extract {
    oneof extract { Http http = 1; }

    message Http {
      oneof extract { Headers headers = 1; }

      message Headers {}
    }
  }
}

message Eos {
  oneof end {
    uint32 grpc_status_code = 1;
    uint32 reset_error_code = 2;
  }
}

message TapEvent {
  net.TcpAddress source = 1;
  EndpointMeta source_meta = 5;

  RouteMeta route_meta = 7;

  net.TcpAddress destination = 2;
  EndpointMeta destination_meta = 4;

  ProxyDirection proxy_direction = 6;
  enum ProxyDirection {
    UNKNOWN = 0;
    INBOUND = 1;
    OUTBOUND = 2;
  }

  oneof event { Http http = 3; }

  message EndpointMeta { map<string, string> labels = 1; }

  message RouteMeta { map<string, string> labels = 1; }

  message Http {
    oneof event {
      RequestInit request_init = 1;
      ResponseInit response_init = 2;
      ResponseEnd response_end = 3;
    }

    message StreamId {
      // A randomized base (stable across a process's runtime)
      uint32 base = 1;

      // A stream id unique within the lifetime of `base`.
      uint64 stream = 2;
    }

    message RequestInit {
      StreamId id = 1;
      http_types.HttpMethod method = 2;
      http_types.Scheme scheme = 3;
      string authority = 4;
      string path = 5;
      http_types.Headers headers = 6;
    }

    message ResponseInit {
      StreamId id = 1;

      google.protobuf.Duration since_request_init = 2;

      uint32 http_status = 3;
      http_types.Headers headers = 4;
    }

    message ResponseEnd {
      StreamId id = 1;

      google.protobuf.Duration since_request_init = 2;
      google.protobuf.Duration since_response_init = 3;
      uint64 response_bytes = 4;

      Eos eos = 5;
      http_types.Headers trailers = 6;
    }
  }
}