even more refactoring

proto/cart_actor.proto

@@ -3,66 +3,114 @@ syntax = "proto3";
 package messages;
 
 option go_package = "git.tornberg.me/go-cart-actor/proto;messages";
+
 import "messages.proto";
 
 // -----------------------------------------------------------------------------
-// Cart Actor gRPC API (oneof Envelope Variant)
+// Cart Actor gRPC API (Breaking v2 - Per-Mutation RPCs)
 // -----------------------------------------------------------------------------
-// This version removes the legacy numeric MutationType enum + raw bytes payload
-// approach and replaces it with a strongly typed oneof envelope. Each concrete
-// mutation proto is embedded directly, enabling:
-//   * Type-safe routing server-side (simple type switch on the oneof).
-//   * Direct persistence of MutationEnvelope messages (no custom binary header).
-//   * Elimination of the legacy message handler registry.
+// This version removes the previous MutationEnvelope + Mutate RPC.
+// Each mutation now has its own request wrapper and dedicated RPC method
+// providing simpler, type-focused client stubs and enabling per-mutation
+// metrics, auth and rate limiting.
 //
-// NOTE: Regenerate Go code after editing:
+// Regenerate Go code after editing:
 //   protoc --go_out=. --go_opt=paths=source_relative \
 //          --go-grpc_out=. --go-grpc_opt=paths=source_relative \
 //          proto/cart_actor.proto proto/messages.proto
+//
+// Backward compatibility: This is a breaking change (old clients must update).
 // -----------------------------------------------------------------------------
 
-// MutationEnvelope carries exactly one mutation plus metadata.
-// client_timestamp:
-//   - Optional Unix timestamp provided by the client.
-//   - If zero the server MAY overwrite with its local time.
-message MutationEnvelope {
-  string cart_id = 1;
-  int64 client_timestamp = 2;
-
-  oneof mutation {
-    AddRequest add_request = 10;
-    AddItem add_item = 11;
-    RemoveItem remove_item = 12;
-    RemoveDelivery remove_delivery = 13;
-    ChangeQuantity change_quantity = 14;
-    SetDelivery set_delivery = 15;
-    SetPickupPoint set_pickup_point = 16;
-    CreateCheckoutOrder create_checkout_order = 17;
-    SetCartRequest set_cart_items = 18;
-    OrderCreated order_completed = 19;
+// Shared reply for all mutation RPCs.
+message CartMutationReply {
+  int32 status_code = 1;          // HTTP-like status (200 success, 4xx client, 5xx server)
+  oneof result {
+    CartState state = 2;          // Updated cart state on success
+    string error = 3;             // Error message on failure
   }
+  int64 server_timestamp = 4;     // Server-assigned Unix timestamp (optional auditing)
 }
 
-// MutationReply returns a legacy-style status code plus a JSON payload
-// holding either the updated cart state (on success) or an error string.
-message MutationReply {
-  int32 status_code = 1;
+// Fetch current cart state without mutation.
+message StateRequest {
+  string cart_id = 1;
+}
 
-  // Exactly one of state or error will be set.
+message StateReply {
+  int32 status_code = 1;
   oneof result {
     CartState state = 2;
     string error = 3;
   }
 }
 
-// StateRequest fetches current cart state without mutating.
-message StateRequest {
+// Per-mutation request wrappers. We wrap the existing inner mutation
+// messages (defined in messages.proto) to add cart_id + optional metadata
+// without altering the inner message definitions.
+
+message AddRequestRequest {
   string cart_id = 1;
+  int64 client_timestamp = 2;
+  AddRequest payload = 10;
+}
+
+message AddItemRequest {
+  string cart_id = 1;
+  int64 client_timestamp = 2;
+  AddItem payload = 10;
+}
+
+message RemoveItemRequest {
+  string cart_id = 1;
+  int64 client_timestamp = 2;
+  RemoveItem payload = 10;
+}
+
+message RemoveDeliveryRequest {
+  string cart_id = 1;
+  int64 client_timestamp = 2;
+  RemoveDelivery payload = 10;
+}
+
+message ChangeQuantityRequest {
+  string cart_id = 1;
+  int64 client_timestamp = 2;
+  ChangeQuantity payload = 10;
+}
+
+message SetDeliveryRequest {
+  string cart_id = 1;
+  int64 client_timestamp = 2;
+  SetDelivery payload = 10;
+}
+
+message SetPickupPointRequest {
+  string cart_id = 1;
+  int64 client_timestamp = 2;
+  SetPickupPoint payload = 10;
+}
+
+message CreateCheckoutOrderRequest {
+  string cart_id = 1;
+  int64 client_timestamp = 2;
+  CreateCheckoutOrder payload = 10;
+}
+
+message SetCartItemsRequest {
+  string cart_id = 1;
+  int64 client_timestamp = 2;
+  SetCartRequest payload = 10;
+}
+
+message OrderCompletedRequest {
+  string cart_id = 1;
+  int64 client_timestamp = 2;
+  OrderCreated payload = 10;
 }
 
 // -----------------------------------------------------------------------------
-// CartState represents the full cart snapshot returned by state/mutation replies.
-// Replaces the previous raw JSON payload.
+// Cart state snapshot (unchanged from v1 except envelope removal context)
 // -----------------------------------------------------------------------------
 message CartState {
   string cart_id = 1;
@@ -76,7 +124,6 @@ message CartState {
   string payment_status = 9;
 }
 
-// Lightweight representation of an item in the cart
 message CartItemState {
   int64 id = 1;
   int64 source_item_id = 2;
@@ -105,38 +152,37 @@ message CartItemState {
   int32 stock = 25;
 }
 
-// Delivery / shipping entry
 message DeliveryState {
   int64 id = 1;
   string provider = 2;
   int64 price = 3;
   repeated int64 item_ids = 4;
-  PickupPoint pickup_point = 5;
+  PickupPoint pickup_point = 5; // Defined in messages.proto
 }
 
-// StateReply mirrors MutationReply for consistency.
-message StateReply {
-  int32 status_code = 1;
+// (CheckoutRequest / CheckoutReply removed - checkout handled at HTTP layer)
 
-  oneof result {
-    CartState state = 2;
-    string error = 3;
-  }
-}
-
-// CartActor exposes mutation and state retrieval for remote grains.
+// -----------------------------------------------------------------------------
+// Service definition (per-mutation RPCs + checkout)
+// -----------------------------------------------------------------------------
 service CartActor {
-  // Mutate applies a single mutation to a cart, creating the cart lazily if needed.
-  rpc Mutate(MutationEnvelope) returns (MutationReply);
+  rpc AddRequest(AddRequestRequest) returns (CartMutationReply);
+  rpc AddItem(AddItemRequest) returns (CartMutationReply);
+  rpc RemoveItem(RemoveItemRequest) returns (CartMutationReply);
+  rpc RemoveDelivery(RemoveDeliveryRequest) returns (CartMutationReply);
+  rpc ChangeQuantity(ChangeQuantityRequest) returns (CartMutationReply);
+  rpc SetDelivery(SetDeliveryRequest) returns (CartMutationReply);
+  rpc SetPickupPoint(SetPickupPointRequest) returns (CartMutationReply);
+  // (Checkout RPC removed - handled externally)
+  rpc SetCartItems(SetCartItemsRequest) returns (CartMutationReply);
+  rpc OrderCompleted(OrderCompletedRequest) returns (CartMutationReply);
 
-  // GetState retrieves the cart's current state (JSON).
   rpc GetState(StateRequest) returns (StateReply);
 }
 
 // -----------------------------------------------------------------------------
-// Future Enhancements:
-//   * Replace JSON state payload with a strongly typed CartState proto.
-//   * Add streaming RPC (e.g., WatchState) for live updates.
-//   * Add batch mutations (repeated MutationEnvelope) if performance requires.
-//   * Introduce optimistic concurrency via version fields if external writers appear.
+// Future enhancements:
+// * BatchMutate RPC (repeated heterogeneous mutations)
+// * Streaming state updates (WatchState)
+// * Versioning / optimistic concurrency control
 // -----------------------------------------------------------------------------