syntax = "proto3";

// Package scrabble.edge.v1 is the client <-> gateway Connect-RPC contract. It is
// deliberately minimal (ARCHITECTURE.md §2): a single unary Execute that routes
// by message_type, and a server-streaming Subscribe for the in-app live channel.
// The actual request/response and event bodies travel as FlatBuffers bytes in the
// payload fields (pkg/fbs). The session token rides in the Authorization header,
// not the envelope (no per-request signing — ARCHITECTURE.md §3).
package scrabble.edge.v1;

option go_package = "scrabble/gateway/proto/edge/v1;edgev1";

// Gateway is the public edge service.
service Gateway {
  // Execute runs one unary operation identified by message_type. Auth operations
  // (auth.*) are unauthenticated and return a minted session; all others require
  // a valid session token in the Authorization header.
  rpc Execute(ExecuteRequest) returns (ExecuteResponse);
  // Subscribe opens the in-app live-event stream for the authenticated session.
  rpc Subscribe(SubscribeRequest) returns (stream Event);
}

// ExecuteRequest is the unary envelope. message_type selects the operation;
// payload is its FlatBuffers-encoded request body; request_id is an optional
// client correlation id echoed back.
message ExecuteRequest {
  string message_type = 1;
  bytes payload = 2;
  string request_id = 3;
}

// ExecuteResponse is the unary reply. result_code is "ok" on success or a stable
// error code; payload is the FlatBuffers-encoded response body (empty on error).
message ExecuteResponse {
  string request_id = 1;
  string result_code = 2;
  bytes payload = 3;
  // message is an optional, already-localized human-readable reason a domain outcome may carry for
  // the user (e.g. a payment-unavailable explanation set by an operator). Additive and
  // frozen-contract-safe; empty for the common case where result_code alone suffices.
  string message = 4;
}

// SubscribeRequest opens the live stream. It is empty: the session is taken from
// the Authorization header.
message SubscribeRequest {}

// Event is one live event. kind is the notification catalog kind; payload is its
// FlatBuffers-encoded body; event_id is a correlation id.
message Event {
  string kind = 1;
  bytes payload = 2;
  string event_id = 3;
}
