complete rewrite to grpc

proto/cart_actor.proto

@@ -0,0 +1,89 @@
+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.
+// -----------------------------------------------------------------------------