syntax = "proto3";

package messages;

option go_package = ".;messages";

// -----------------------------------------------------------------------------
// Cart Actor gRPC API (Envelope Variant)
// -----------------------------------------------------------------------------
// This service replaces the legacy custom TCP frame protocol used on port 1337.
// It keeps the existing per-mutation proto messages (defined in messages.proto)
// serialized into an opaque `bytes payload` field for minimal refactor cost.
// The numeric values in MutationType MUST match the legacy message type
// constants (see message-types.go) so persisted event logs replay correctly.
// -----------------------------------------------------------------------------

// MutationType corresponds 1:1 with the legacy uint16 message type constants.
enum MutationType {
  MUTATION_TYPE_UNSPECIFIED        = 0;
  MUTATION_ADD_REQUEST             = 1;
  MUTATION_ADD_ITEM                = 2;
  // (3 was unused / reserved in legacy framing)
  MUTATION_REMOVE_ITEM             = 4;
  MUTATION_REMOVE_DELIVERY         = 5;
  MUTATION_CHANGE_QUANTITY         = 6;
  MUTATION_SET_DELIVERY            = 7;
  MUTATION_SET_PICKUP_POINT        = 8;
  MUTATION_CREATE_CHECKOUT_ORDER   = 9;
  MUTATION_SET_CART_ITEMS          = 10;
  MUTATION_ORDER_COMPLETED         = 11;
}

// MutationRequest is an envelope:
// - cart_id: string form of CartId (legacy 16-byte array truncated/padded).
// - type: mutation kind (see enum).
// - payload: serialized underlying proto message (AddRequest, AddItem, etc.).
// - client_timestamp: optional unix timestamp; server sets if zero.
message MutationRequest {
  string cart_id        = 1;
  MutationType type     = 2;
  bytes payload         = 3;
  int64 client_timestamp = 4;
}

// MutationReply returns a status code (legacy semantics) plus a JSON payload
// representing the full cart state (or an error message if non-200).
message MutationReply {
  int32 status_code = 1;
  bytes payload     = 2; // JSON cart state or error string
}

// StateRequest fetches current cart state without mutation.
message StateRequest {
  string cart_id = 1;
}

// StateReply mirrors MutationReply for consistency.
message StateReply {
  int32 status_code = 1;
  bytes payload     = 2; // JSON cart state or error string
}

// CartActor exposes mutation and state retrieval for remote grains.
service CartActor {
  // Mutate applies a single mutation to a cart, creating the cart lazily if needed.
  rpc Mutate(MutationRequest) returns (MutationReply);

  // GetState retrieves the cart's current state (JSON).
  rpc GetState(StateRequest) returns (StateReply);
}

// -----------------------------------------------------------------------------
// Notes:
//
// 1. Generation:
//    protoc --go_out=. --go_opt=paths=source_relative \
//           --go-grpc_out=. --go-grpc_opt=paths=source_relative \
//           cart_actor.proto
//
// 2. Underlying mutation payloads originate from messages.proto definitions.
//    The server side will route based on MutationType and decode payload bytes
//    using existing handler registry logic.
//
// 3. Future Enhancements:
//    - Replace JSON state payload with a strongly typed CartState proto.
//    - Add streaming RPC (e.g. WatchState) for live updates.
//    - Migrate control plane (negotiate/ownership) into a separate proto
//      (control_plane.proto) as per the migration plan.
// -----------------------------------------------------------------------------