netmaker/grpc/flow/flow.proto

syntax = "proto3";

package netmaker.flow;

option go_package = "github.com/gravitl/netmaker/grpc/flow";

// ============================================================
// BUILD COMMAND:
//
// protoc --go_out=. --go_opt=paths=source_relative --go-grpc_out=. --go-grpc_opt=paths=source_relative grpc/flow/flow.proto
//
// ============================================================

// ============================================================
// ENUMS
// ============================================================

/**
 * Lifecycle stage of a flow event as seen by an netclient.
 * A flow produces:
 *  - EVENT_START   when conntrack entry is created
 *  - EVENT_DESTROY when conntrack entry is removed
 */
enum EventType {
  EVENT_TYPE_UNSPECIFIED = 0;
  EVENT_START = 1;
  EVENT_DESTROY = 2;
}

/**
 * Identifies what kind of participant an IP belongs to.
 */
enum ParticipantType {
  PARTICIPANT_UNSPECIFIED = 0;
  PARTICIPANT_NODE = 1;
  PARTICIPANT_USER = 2;
  PARTICIPANT_EXTCLIENT = 3;
  PARTICIPANT_EGRESS_ROUTE = 4;
  PARTICIPANT_EXTERNAL = 5; // anything not part of the Netmaker network
}

/**
 * Direction of the flow relative to the observing node.
 */
enum Direction {
  DIR_UNSPECIFIED = 0;
  DIR_INGRESS = 1;
  DIR_EGRESS = 2;
}

// ============================================================
// PARTICIPANT STRUCTURE
// ============================================================

/**
 * Fully enriched representation of one endpoint of a flow.
 */
message FlowParticipant {
  string ip = 1;
  ParticipantType type = 2;
  string id = 3;
}

// ============================================================
// RAW AGENT EVENT
// ============================================================

/**
 * Flow event generated by netclient.
 */
message FlowEvent {
  // Flow lifecycle event type (START or DESTROY)
  EventType type = 1;

  // Stable identity
  string flow_id = 2;        // unique per flow
  string network_id = 3;     // network this flow belongs to
  string host_id = 4;        // node reporting this event

  // L3/L4 metadata
  uint32 protocol = 5;
  uint32 src_port = 6;
  uint32 dst_port = 7;
  uint32 icmp_type = 8;
  uint32 icmp_code = 9;

  Direction direction = 10;

  // Participants — enriched by client
  FlowParticipant src = 11;
  FlowParticipant dst = 12;

  // Timestamps (milliseconds since epoch)
  int64 start_ts_ms = 13;
  int64 end_ts_ms = 14;

  // Traffic counters (only valid for destroy events)
  uint64 bytes_sent = 15;
  uint64 bytes_recv = 16;
  uint64 packets_sent = 17;
  uint64 packets_recv = 18;

  // Netfilter conntrack status flags (bitmask)
  uint32 status = 19;

  /**
   * Version used by ClickHouse for merging.
   * Must be strictly increasing for START → DESTROY.
   * Usually equal to the netclient event timestamp (ms).
   */
  int64 version = 20;
}

// ============================================================
// BATCHING AND STREAMING
// ============================================================

/**
 * Envelope sent by netclients containing multiple FlowEvents.
 */
message FlowEnvelope {
  repeated FlowEvent events = 1;
}

/**
 * Response from server acknowledging receipt of a batch.
 */
message FlowResponse {
  bool success = 1;           // true if batch was accepted
  string error = 2;           // optional error information
}

// ============================================================
// SERVICE
// ============================================================

/**
 * Bidirectional streaming:
 *  - Agents continuously send FlowEnvelope batches.
 *  - Server replies with FlowResponse ACKs.
 */
service FlowService {
  rpc StreamFlows(stream FlowEnvelope) returns (stream FlowResponse);
}