complete rewrite to grpc

proto/cart_actor.pb.go

@@ -0,0 +1,420 @@
+// Code generated by protoc-gen-go. DO NOT EDIT.
+// versions:
+// 	protoc-gen-go v1.36.10
+// 	protoc        v3.21.12
+// source: cart_actor.proto
+
+package messages
+
+import (
+	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
+	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
+	reflect "reflect"
+	sync "sync"
+	unsafe "unsafe"
+)
+
+const (
+	// Verify that this generated code is sufficiently up-to-date.
+	_ = protoimpl.EnforceVersion(20 - protoimpl.MinVersion)
+	// Verify that runtime/protoimpl is sufficiently up-to-date.
+	_ = protoimpl.EnforceVersion(protoimpl.MaxVersion - 20)
+)
+
+// MutationType corresponds 1:1 with the legacy uint16 message type constants.
+type MutationType int32
+
+const (
+	MutationType_MUTATION_TYPE_UNSPECIFIED MutationType = 0
+	MutationType_MUTATION_ADD_REQUEST      MutationType = 1
+	MutationType_MUTATION_ADD_ITEM         MutationType = 2
+	// (3 was unused / reserved in legacy framing)
+	MutationType_MUTATION_REMOVE_ITEM           MutationType = 4
+	MutationType_MUTATION_REMOVE_DELIVERY       MutationType = 5
+	MutationType_MUTATION_CHANGE_QUANTITY       MutationType = 6
+	MutationType_MUTATION_SET_DELIVERY          MutationType = 7
+	MutationType_MUTATION_SET_PICKUP_POINT      MutationType = 8
+	MutationType_MUTATION_CREATE_CHECKOUT_ORDER MutationType = 9
+	MutationType_MUTATION_SET_CART_ITEMS        MutationType = 10
+	MutationType_MUTATION_ORDER_COMPLETED       MutationType = 11
+)
+
+// Enum value maps for MutationType.
+var (
+	MutationType_name = map[int32]string{
+		0:  "MUTATION_TYPE_UNSPECIFIED",
+		1:  "MUTATION_ADD_REQUEST",
+		2:  "MUTATION_ADD_ITEM",
+		4:  "MUTATION_REMOVE_ITEM",
+		5:  "MUTATION_REMOVE_DELIVERY",
+		6:  "MUTATION_CHANGE_QUANTITY",
+		7:  "MUTATION_SET_DELIVERY",
+		8:  "MUTATION_SET_PICKUP_POINT",
+		9:  "MUTATION_CREATE_CHECKOUT_ORDER",
+		10: "MUTATION_SET_CART_ITEMS",
+		11: "MUTATION_ORDER_COMPLETED",
+	}
+	MutationType_value = map[string]int32{
+		"MUTATION_TYPE_UNSPECIFIED":      0,
+		"MUTATION_ADD_REQUEST":           1,
+		"MUTATION_ADD_ITEM":              2,
+		"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,
+	}
+)
+
+func (x MutationType) Enum() *MutationType {
+	p := new(MutationType)
+	*p = x
+	return p
+}
+
+func (x MutationType) String() string {
+	return protoimpl.X.EnumStringOf(x.Descriptor(), protoreflect.EnumNumber(x))
+}
+
+func (MutationType) Descriptor() protoreflect.EnumDescriptor {
+	return file_cart_actor_proto_enumTypes[0].Descriptor()
+}
+
+func (MutationType) Type() protoreflect.EnumType {
+	return &file_cart_actor_proto_enumTypes[0]
+}
+
+func (x MutationType) Number() protoreflect.EnumNumber {
+	return protoreflect.EnumNumber(x)
+}
+
+// Deprecated: Use MutationType.Descriptor instead.
+func (MutationType) EnumDescriptor() ([]byte, []int) {
+	return file_cart_actor_proto_rawDescGZIP(), []int{0}
+}
+
+// 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.
+type MutationRequest struct {
+	state           protoimpl.MessageState `protogen:"open.v1"`
+	CartId          string                 `protobuf:"bytes,1,opt,name=cart_id,json=cartId,proto3" json:"cart_id,omitempty"`
+	Type            MutationType           `protobuf:"varint,2,opt,name=type,proto3,enum=messages.MutationType" json:"type,omitempty"`
+	Payload         []byte                 `protobuf:"bytes,3,opt,name=payload,proto3" json:"payload,omitempty"`
+	ClientTimestamp int64                  `protobuf:"varint,4,opt,name=client_timestamp,json=clientTimestamp,proto3" json:"client_timestamp,omitempty"`
+	unknownFields   protoimpl.UnknownFields
+	sizeCache       protoimpl.SizeCache
+}
+
+func (x *MutationRequest) Reset() {
+	*x = MutationRequest{}
+	mi := &file_cart_actor_proto_msgTypes[0]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *MutationRequest) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*MutationRequest) ProtoMessage() {}
+
+func (x *MutationRequest) ProtoReflect() protoreflect.Message {
+	mi := &file_cart_actor_proto_msgTypes[0]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use MutationRequest.ProtoReflect.Descriptor instead.
+func (*MutationRequest) Descriptor() ([]byte, []int) {
+	return file_cart_actor_proto_rawDescGZIP(), []int{0}
+}
+
+func (x *MutationRequest) GetCartId() string {
+	if x != nil {
+		return x.CartId
+	}
+	return ""
+}
+
+func (x *MutationRequest) GetType() MutationType {
+	if x != nil {
+		return x.Type
+	}
+	return MutationType_MUTATION_TYPE_UNSPECIFIED
+}
+
+func (x *MutationRequest) GetPayload() []byte {
+	if x != nil {
+		return x.Payload
+	}
+	return nil
+}
+
+func (x *MutationRequest) GetClientTimestamp() int64 {
+	if x != nil {
+		return x.ClientTimestamp
+	}
+	return 0
+}
+
+// MutationReply returns a status code (legacy semantics) plus a JSON payload
+// representing the full cart state (or an error message if non-200).
+type MutationReply struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	StatusCode    int32                  `protobuf:"varint,1,opt,name=status_code,json=statusCode,proto3" json:"status_code,omitempty"`
+	Payload       []byte                 `protobuf:"bytes,2,opt,name=payload,proto3" json:"payload,omitempty"` // JSON cart state or error string
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *MutationReply) Reset() {
+	*x = MutationReply{}
+	mi := &file_cart_actor_proto_msgTypes[1]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *MutationReply) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*MutationReply) ProtoMessage() {}
+
+func (x *MutationReply) ProtoReflect() protoreflect.Message {
+	mi := &file_cart_actor_proto_msgTypes[1]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use MutationReply.ProtoReflect.Descriptor instead.
+func (*MutationReply) Descriptor() ([]byte, []int) {
+	return file_cart_actor_proto_rawDescGZIP(), []int{1}
+}
+
+func (x *MutationReply) GetStatusCode() int32 {
+	if x != nil {
+		return x.StatusCode
+	}
+	return 0
+}
+
+func (x *MutationReply) GetPayload() []byte {
+	if x != nil {
+		return x.Payload
+	}
+	return nil
+}
+
+// StateRequest fetches current cart state without mutation.
+type StateRequest struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	CartId        string                 `protobuf:"bytes,1,opt,name=cart_id,json=cartId,proto3" json:"cart_id,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *StateRequest) Reset() {
+	*x = StateRequest{}
+	mi := &file_cart_actor_proto_msgTypes[2]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *StateRequest) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*StateRequest) ProtoMessage() {}
+
+func (x *StateRequest) ProtoReflect() protoreflect.Message {
+	mi := &file_cart_actor_proto_msgTypes[2]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use StateRequest.ProtoReflect.Descriptor instead.
+func (*StateRequest) Descriptor() ([]byte, []int) {
+	return file_cart_actor_proto_rawDescGZIP(), []int{2}
+}
+
+func (x *StateRequest) GetCartId() string {
+	if x != nil {
+		return x.CartId
+	}
+	return ""
+}
+
+// StateReply mirrors MutationReply for consistency.
+type StateReply struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	StatusCode    int32                  `protobuf:"varint,1,opt,name=status_code,json=statusCode,proto3" json:"status_code,omitempty"`
+	Payload       []byte                 `protobuf:"bytes,2,opt,name=payload,proto3" json:"payload,omitempty"` // JSON cart state or error string
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *StateReply) Reset() {
+	*x = StateReply{}
+	mi := &file_cart_actor_proto_msgTypes[3]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *StateReply) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*StateReply) ProtoMessage() {}
+
+func (x *StateReply) ProtoReflect() protoreflect.Message {
+	mi := &file_cart_actor_proto_msgTypes[3]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use StateReply.ProtoReflect.Descriptor instead.
+func (*StateReply) Descriptor() ([]byte, []int) {
+	return file_cart_actor_proto_rawDescGZIP(), []int{3}
+}
+
+func (x *StateReply) GetStatusCode() int32 {
+	if x != nil {
+		return x.StatusCode
+	}
+	return 0
+}
+
+func (x *StateReply) GetPayload() []byte {
+	if x != nil {
+		return x.Payload
+	}
+	return nil
+}
+
+var File_cart_actor_proto protoreflect.FileDescriptor
+
+const file_cart_actor_proto_rawDesc = "" +
+	"\n" +
+	"\x10cart_actor.proto\x12\bmessages\"\x9b\x01\n" +
+	"\x0fMutationRequest\x12\x17\n" +
+	"\acart_id\x18\x01 \x01(\tR\x06cartId\x12*\n" +
+	"\x04type\x18\x02 \x01(\x0e2\x16.messages.MutationTypeR\x04type\x12\x18\n" +
+	"\apayload\x18\x03 \x01(\fR\apayload\x12)\n" +
+	"\x10client_timestamp\x18\x04 \x01(\x03R\x0fclientTimestamp\"J\n" +
+	"\rMutationReply\x12\x1f\n" +
+	"\vstatus_code\x18\x01 \x01(\x05R\n" +
+	"statusCode\x12\x18\n" +
+	"\apayload\x18\x02 \x01(\fR\apayload\"'\n" +
+	"\fStateRequest\x12\x17\n" +
+	"\acart_id\x18\x01 \x01(\tR\x06cartId\"G\n" +
+	"\n" +
+	"StateReply\x12\x1f\n" +
+	"\vstatus_code\x18\x01 \x01(\x05R\n" +
+	"statusCode\x12\x18\n" +
+	"\apayload\x18\x02 \x01(\fR\apayload*\xcd\x02\n" +
+	"\fMutationType\x12\x1d\n" +
+	"\x19MUTATION_TYPE_UNSPECIFIED\x10\x00\x12\x18\n" +
+	"\x14MUTATION_ADD_REQUEST\x10\x01\x12\x15\n" +
+	"\x11MUTATION_ADD_ITEM\x10\x02\x12\x18\n" +
+	"\x14MUTATION_REMOVE_ITEM\x10\x04\x12\x1c\n" +
+	"\x18MUTATION_REMOVE_DELIVERY\x10\x05\x12\x1c\n" +
+	"\x18MUTATION_CHANGE_QUANTITY\x10\x06\x12\x19\n" +
+	"\x15MUTATION_SET_DELIVERY\x10\a\x12\x1d\n" +
+	"\x19MUTATION_SET_PICKUP_POINT\x10\b\x12\"\n" +
+	"\x1eMUTATION_CREATE_CHECKOUT_ORDER\x10\t\x12\x1b\n" +
+	"\x17MUTATION_SET_CART_ITEMS\x10\n" +
+	"\x12\x1c\n" +
+	"\x18MUTATION_ORDER_COMPLETED\x10\v2\x83\x01\n" +
+	"\tCartActor\x12<\n" +
+	"\x06Mutate\x12\x19.messages.MutationRequest\x1a\x17.messages.MutationReply\x128\n" +
+	"\bGetState\x12\x16.messages.StateRequest\x1a\x14.messages.StateReplyB\fZ\n" +
+	".;messagesb\x06proto3"
+
+var (
+	file_cart_actor_proto_rawDescOnce sync.Once
+	file_cart_actor_proto_rawDescData []byte
+)
+
+func file_cart_actor_proto_rawDescGZIP() []byte {
+	file_cart_actor_proto_rawDescOnce.Do(func() {
+		file_cart_actor_proto_rawDescData = protoimpl.X.CompressGZIP(unsafe.Slice(unsafe.StringData(file_cart_actor_proto_rawDesc), len(file_cart_actor_proto_rawDesc)))
+	})
+	return file_cart_actor_proto_rawDescData
+}
+
+var file_cart_actor_proto_enumTypes = make([]protoimpl.EnumInfo, 1)
+var file_cart_actor_proto_msgTypes = make([]protoimpl.MessageInfo, 4)
+var file_cart_actor_proto_goTypes = []any{
+	(MutationType)(0),       // 0: messages.MutationType
+	(*MutationRequest)(nil), // 1: messages.MutationRequest
+	(*MutationReply)(nil),   // 2: messages.MutationReply
+	(*StateRequest)(nil),    // 3: messages.StateRequest
+	(*StateReply)(nil),      // 4: messages.StateReply
+}
+var file_cart_actor_proto_depIdxs = []int32{
+	0, // 0: messages.MutationRequest.type:type_name -> messages.MutationType
+	1, // 1: messages.CartActor.Mutate:input_type -> messages.MutationRequest
+	3, // 2: messages.CartActor.GetState:input_type -> messages.StateRequest
+	2, // 3: messages.CartActor.Mutate:output_type -> messages.MutationReply
+	4, // 4: messages.CartActor.GetState:output_type -> messages.StateReply
+	3, // [3:5] is the sub-list for method output_type
+	1, // [1:3] is the sub-list for method input_type
+	1, // [1:1] is the sub-list for extension type_name
+	1, // [1:1] is the sub-list for extension extendee
+	0, // [0:1] is the sub-list for field type_name
+}
+
+func init() { file_cart_actor_proto_init() }
+func file_cart_actor_proto_init() {
+	if File_cart_actor_proto != nil {
+		return
+	}
+	type x struct{}
+	out := protoimpl.TypeBuilder{
+		File: protoimpl.DescBuilder{
+			GoPackagePath: reflect.TypeOf(x{}).PkgPath(),
+			RawDescriptor: unsafe.Slice(unsafe.StringData(file_cart_actor_proto_rawDesc), len(file_cart_actor_proto_rawDesc)),
+			NumEnums:      1,
+			NumMessages:   4,
+			NumExtensions: 0,
+			NumServices:   1,
+		},
+		GoTypes:           file_cart_actor_proto_goTypes,
+		DependencyIndexes: file_cart_actor_proto_depIdxs,
+		EnumInfos:         file_cart_actor_proto_enumTypes,
+		MessageInfos:      file_cart_actor_proto_msgTypes,
+	}.Build()
+	File_cart_actor_proto = out.File
+	file_cart_actor_proto_goTypes = nil
+	file_cart_actor_proto_depIdxs = nil
+}

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.
+// -----------------------------------------------------------------------------

proto/cart_actor_grpc.pb.go

@@ -0,0 +1,167 @@
+// Code generated by protoc-gen-go-grpc. DO NOT EDIT.
+// versions:
+// - protoc-gen-go-grpc v1.5.1
+// - protoc             v3.21.12
+// source: cart_actor.proto
+
+package messages
+
+import (
+	context "context"
+	grpc "google.golang.org/grpc"
+	codes "google.golang.org/grpc/codes"
+	status "google.golang.org/grpc/status"
+)
+
+// This is a compile-time assertion to ensure that this generated file
+// is compatible with the grpc package it is being compiled against.
+// Requires gRPC-Go v1.64.0 or later.
+const _ = grpc.SupportPackageIsVersion9
+
+const (
+	CartActor_Mutate_FullMethodName   = "/messages.CartActor/Mutate"
+	CartActor_GetState_FullMethodName = "/messages.CartActor/GetState"
+)
+
+// CartActorClient is the client API for CartActor service.
+//
+// For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream.
+//
+// CartActor exposes mutation and state retrieval for remote grains.
+type CartActorClient interface {
+	// Mutate applies a single mutation to a cart, creating the cart lazily if needed.
+	Mutate(ctx context.Context, in *MutationRequest, opts ...grpc.CallOption) (*MutationReply, error)
+	// GetState retrieves the cart's current state (JSON).
+	GetState(ctx context.Context, in *StateRequest, opts ...grpc.CallOption) (*StateReply, error)
+}
+
+type cartActorClient struct {
+	cc grpc.ClientConnInterface
+}
+
+func NewCartActorClient(cc grpc.ClientConnInterface) CartActorClient {
+	return &cartActorClient{cc}
+}
+
+func (c *cartActorClient) Mutate(ctx context.Context, in *MutationRequest, opts ...grpc.CallOption) (*MutationReply, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(MutationReply)
+	err := c.cc.Invoke(ctx, CartActor_Mutate_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func (c *cartActorClient) GetState(ctx context.Context, in *StateRequest, opts ...grpc.CallOption) (*StateReply, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(StateReply)
+	err := c.cc.Invoke(ctx, CartActor_GetState_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+// CartActorServer is the server API for CartActor service.
+// All implementations must embed UnimplementedCartActorServer
+// for forward compatibility.
+//
+// CartActor exposes mutation and state retrieval for remote grains.
+type CartActorServer interface {
+	// Mutate applies a single mutation to a cart, creating the cart lazily if needed.
+	Mutate(context.Context, *MutationRequest) (*MutationReply, error)
+	// GetState retrieves the cart's current state (JSON).
+	GetState(context.Context, *StateRequest) (*StateReply, error)
+	mustEmbedUnimplementedCartActorServer()
+}
+
+// UnimplementedCartActorServer must be embedded to have
+// forward compatible implementations.
+//
+// NOTE: this should be embedded by value instead of pointer to avoid a nil
+// pointer dereference when methods are called.
+type UnimplementedCartActorServer struct{}
+
+func (UnimplementedCartActorServer) Mutate(context.Context, *MutationRequest) (*MutationReply, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method Mutate not implemented")
+}
+func (UnimplementedCartActorServer) GetState(context.Context, *StateRequest) (*StateReply, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method GetState not implemented")
+}
+func (UnimplementedCartActorServer) mustEmbedUnimplementedCartActorServer() {}
+func (UnimplementedCartActorServer) testEmbeddedByValue()                   {}
+
+// UnsafeCartActorServer may be embedded to opt out of forward compatibility for this service.
+// Use of this interface is not recommended, as added methods to CartActorServer will
+// result in compilation errors.
+type UnsafeCartActorServer interface {
+	mustEmbedUnimplementedCartActorServer()
+}
+
+func RegisterCartActorServer(s grpc.ServiceRegistrar, srv CartActorServer) {
+	// If the following call pancis, it indicates UnimplementedCartActorServer was
+	// embedded by pointer and is nil.  This will cause panics if an
+	// unimplemented method is ever invoked, so we test this at initialization
+	// time to prevent it from happening at runtime later due to I/O.
+	if t, ok := srv.(interface{ testEmbeddedByValue() }); ok {
+		t.testEmbeddedByValue()
+	}
+	s.RegisterService(&CartActor_ServiceDesc, srv)
+}
+
+func _CartActor_Mutate_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(MutationRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(CartActorServer).Mutate(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: CartActor_Mutate_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(CartActorServer).Mutate(ctx, req.(*MutationRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+func _CartActor_GetState_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(StateRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(CartActorServer).GetState(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: CartActor_GetState_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(CartActorServer).GetState(ctx, req.(*StateRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+// CartActor_ServiceDesc is the grpc.ServiceDesc for CartActor service.
+// It's only intended for direct use with grpc.RegisterService,
+// and not to be introspected or modified (even as a copy)
+var CartActor_ServiceDesc = grpc.ServiceDesc{
+	ServiceName: "messages.CartActor",
+	HandlerType: (*CartActorServer)(nil),
+	Methods: []grpc.MethodDesc{
+		{
+			MethodName: "Mutate",
+			Handler:    _CartActor_Mutate_Handler,
+		},
+		{
+			MethodName: "GetState",
+			Handler:    _CartActor_GetState_Handler,
+		},
+	},
+	Streams:  []grpc.StreamDesc{},
+	Metadata: "cart_actor.proto",
+}

proto/control_plane.pb.go

@@ -0,0 +1,496 @@
+// Code generated by protoc-gen-go. DO NOT EDIT.
+// versions:
+// 	protoc-gen-go v1.36.10
+// 	protoc        v3.21.12
+// source: control_plane.proto
+
+package messages
+
+import (
+	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
+	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
+	reflect "reflect"
+	sync "sync"
+	unsafe "unsafe"
+)
+
+const (
+	// Verify that this generated code is sufficiently up-to-date.
+	_ = protoimpl.EnforceVersion(20 - protoimpl.MinVersion)
+	// Verify that runtime/protoimpl is sufficiently up-to-date.
+	_ = protoimpl.EnforceVersion(protoimpl.MaxVersion - 20)
+)
+
+// Empty request placeholder (common pattern).
+type Empty struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *Empty) Reset() {
+	*x = Empty{}
+	mi := &file_control_plane_proto_msgTypes[0]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *Empty) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*Empty) ProtoMessage() {}
+
+func (x *Empty) ProtoReflect() protoreflect.Message {
+	mi := &file_control_plane_proto_msgTypes[0]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use Empty.ProtoReflect.Descriptor instead.
+func (*Empty) Descriptor() ([]byte, []int) {
+	return file_control_plane_proto_rawDescGZIP(), []int{0}
+}
+
+// Ping reply includes responding host and its current unix time (seconds).
+type PingReply struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	Host          string                 `protobuf:"bytes,1,opt,name=host,proto3" json:"host,omitempty"`
+	UnixTime      int64                  `protobuf:"varint,2,opt,name=unix_time,json=unixTime,proto3" json:"unix_time,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *PingReply) Reset() {
+	*x = PingReply{}
+	mi := &file_control_plane_proto_msgTypes[1]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *PingReply) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*PingReply) ProtoMessage() {}
+
+func (x *PingReply) ProtoReflect() protoreflect.Message {
+	mi := &file_control_plane_proto_msgTypes[1]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use PingReply.ProtoReflect.Descriptor instead.
+func (*PingReply) Descriptor() ([]byte, []int) {
+	return file_control_plane_proto_rawDescGZIP(), []int{1}
+}
+
+func (x *PingReply) GetHost() string {
+	if x != nil {
+		return x.Host
+	}
+	return ""
+}
+
+func (x *PingReply) GetUnixTime() int64 {
+	if x != nil {
+		return x.UnixTime
+	}
+	return 0
+}
+
+// NegotiateRequest carries the caller's full view of known hosts (including self).
+type NegotiateRequest struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	KnownHosts    []string               `protobuf:"bytes,1,rep,name=known_hosts,json=knownHosts,proto3" json:"known_hosts,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *NegotiateRequest) Reset() {
+	*x = NegotiateRequest{}
+	mi := &file_control_plane_proto_msgTypes[2]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *NegotiateRequest) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*NegotiateRequest) ProtoMessage() {}
+
+func (x *NegotiateRequest) ProtoReflect() protoreflect.Message {
+	mi := &file_control_plane_proto_msgTypes[2]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use NegotiateRequest.ProtoReflect.Descriptor instead.
+func (*NegotiateRequest) Descriptor() ([]byte, []int) {
+	return file_control_plane_proto_rawDescGZIP(), []int{2}
+}
+
+func (x *NegotiateRequest) GetKnownHosts() []string {
+	if x != nil {
+		return x.KnownHosts
+	}
+	return nil
+}
+
+// NegotiateReply returns the callee's healthy hosts (including itself).
+type NegotiateReply struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	Hosts         []string               `protobuf:"bytes,1,rep,name=hosts,proto3" json:"hosts,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *NegotiateReply) Reset() {
+	*x = NegotiateReply{}
+	mi := &file_control_plane_proto_msgTypes[3]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *NegotiateReply) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*NegotiateReply) ProtoMessage() {}
+
+func (x *NegotiateReply) ProtoReflect() protoreflect.Message {
+	mi := &file_control_plane_proto_msgTypes[3]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use NegotiateReply.ProtoReflect.Descriptor instead.
+func (*NegotiateReply) Descriptor() ([]byte, []int) {
+	return file_control_plane_proto_rawDescGZIP(), []int{3}
+}
+
+func (x *NegotiateReply) GetHosts() []string {
+	if x != nil {
+		return x.Hosts
+	}
+	return nil
+}
+
+// CartIdsReply returns the list of cart IDs (string form) currently owned locally.
+type CartIdsReply struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	CartIds       []string               `protobuf:"bytes,1,rep,name=cart_ids,json=cartIds,proto3" json:"cart_ids,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *CartIdsReply) Reset() {
+	*x = CartIdsReply{}
+	mi := &file_control_plane_proto_msgTypes[4]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *CartIdsReply) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*CartIdsReply) ProtoMessage() {}
+
+func (x *CartIdsReply) ProtoReflect() protoreflect.Message {
+	mi := &file_control_plane_proto_msgTypes[4]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use CartIdsReply.ProtoReflect.Descriptor instead.
+func (*CartIdsReply) Descriptor() ([]byte, []int) {
+	return file_control_plane_proto_rawDescGZIP(), []int{4}
+}
+
+func (x *CartIdsReply) GetCartIds() []string {
+	if x != nil {
+		return x.CartIds
+	}
+	return nil
+}
+
+// OwnerChangeRequest notifies peers that ownership of a cart moved (or is moving) to new_host.
+type OwnerChangeRequest struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	CartId        string                 `protobuf:"bytes,1,opt,name=cart_id,json=cartId,proto3" json:"cart_id,omitempty"`
+	NewHost       string                 `protobuf:"bytes,2,opt,name=new_host,json=newHost,proto3" json:"new_host,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *OwnerChangeRequest) Reset() {
+	*x = OwnerChangeRequest{}
+	mi := &file_control_plane_proto_msgTypes[5]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *OwnerChangeRequest) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*OwnerChangeRequest) ProtoMessage() {}
+
+func (x *OwnerChangeRequest) ProtoReflect() protoreflect.Message {
+	mi := &file_control_plane_proto_msgTypes[5]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use OwnerChangeRequest.ProtoReflect.Descriptor instead.
+func (*OwnerChangeRequest) Descriptor() ([]byte, []int) {
+	return file_control_plane_proto_rawDescGZIP(), []int{5}
+}
+
+func (x *OwnerChangeRequest) GetCartId() string {
+	if x != nil {
+		return x.CartId
+	}
+	return ""
+}
+
+func (x *OwnerChangeRequest) GetNewHost() string {
+	if x != nil {
+		return x.NewHost
+	}
+	return ""
+}
+
+// OwnerChangeAck indicates acceptance or rejection of an ownership change.
+type OwnerChangeAck struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	Accepted      bool                   `protobuf:"varint,1,opt,name=accepted,proto3" json:"accepted,omitempty"`
+	Message       string                 `protobuf:"bytes,2,opt,name=message,proto3" json:"message,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *OwnerChangeAck) Reset() {
+	*x = OwnerChangeAck{}
+	mi := &file_control_plane_proto_msgTypes[6]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *OwnerChangeAck) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*OwnerChangeAck) ProtoMessage() {}
+
+func (x *OwnerChangeAck) ProtoReflect() protoreflect.Message {
+	mi := &file_control_plane_proto_msgTypes[6]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use OwnerChangeAck.ProtoReflect.Descriptor instead.
+func (*OwnerChangeAck) Descriptor() ([]byte, []int) {
+	return file_control_plane_proto_rawDescGZIP(), []int{6}
+}
+
+func (x *OwnerChangeAck) GetAccepted() bool {
+	if x != nil {
+		return x.Accepted
+	}
+	return false
+}
+
+func (x *OwnerChangeAck) GetMessage() string {
+	if x != nil {
+		return x.Message
+	}
+	return ""
+}
+
+// ClosingNotice notifies peers this host is terminating (so they can drop / re-resolve).
+type ClosingNotice struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	Host          string                 `protobuf:"bytes,1,opt,name=host,proto3" json:"host,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *ClosingNotice) Reset() {
+	*x = ClosingNotice{}
+	mi := &file_control_plane_proto_msgTypes[7]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *ClosingNotice) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*ClosingNotice) ProtoMessage() {}
+
+func (x *ClosingNotice) ProtoReflect() protoreflect.Message {
+	mi := &file_control_plane_proto_msgTypes[7]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use ClosingNotice.ProtoReflect.Descriptor instead.
+func (*ClosingNotice) Descriptor() ([]byte, []int) {
+	return file_control_plane_proto_rawDescGZIP(), []int{7}
+}
+
+func (x *ClosingNotice) GetHost() string {
+	if x != nil {
+		return x.Host
+	}
+	return ""
+}
+
+var File_control_plane_proto protoreflect.FileDescriptor
+
+const file_control_plane_proto_rawDesc = "" +
+	"\n" +
+	"\x13control_plane.proto\x12\bmessages\"\a\n" +
+	"\x05Empty\"<\n" +
+	"\tPingReply\x12\x12\n" +
+	"\x04host\x18\x01 \x01(\tR\x04host\x12\x1b\n" +
+	"\tunix_time\x18\x02 \x01(\x03R\bunixTime\"3\n" +
+	"\x10NegotiateRequest\x12\x1f\n" +
+	"\vknown_hosts\x18\x01 \x03(\tR\n" +
+	"knownHosts\"&\n" +
+	"\x0eNegotiateReply\x12\x14\n" +
+	"\x05hosts\x18\x01 \x03(\tR\x05hosts\")\n" +
+	"\fCartIdsReply\x12\x19\n" +
+	"\bcart_ids\x18\x01 \x03(\tR\acartIds\"H\n" +
+	"\x12OwnerChangeRequest\x12\x17\n" +
+	"\acart_id\x18\x01 \x01(\tR\x06cartId\x12\x19\n" +
+	"\bnew_host\x18\x02 \x01(\tR\anewHost\"F\n" +
+	"\x0eOwnerChangeAck\x12\x1a\n" +
+	"\baccepted\x18\x01 \x01(\bR\baccepted\x12\x18\n" +
+	"\amessage\x18\x02 \x01(\tR\amessage\"#\n" +
+	"\rClosingNotice\x12\x12\n" +
+	"\x04host\x18\x01 \x01(\tR\x04host2\xbc\x02\n" +
+	"\fControlPlane\x12,\n" +
+	"\x04Ping\x12\x0f.messages.Empty\x1a\x13.messages.PingReply\x12A\n" +
+	"\tNegotiate\x12\x1a.messages.NegotiateRequest\x1a\x18.messages.NegotiateReply\x125\n" +
+	"\n" +
+	"GetCartIds\x12\x0f.messages.Empty\x1a\x16.messages.CartIdsReply\x12F\n" +
+	"\fConfirmOwner\x12\x1c.messages.OwnerChangeRequest\x1a\x18.messages.OwnerChangeAck\x12<\n" +
+	"\aClosing\x12\x17.messages.ClosingNotice\x1a\x18.messages.OwnerChangeAckB\fZ\n" +
+	".;messagesb\x06proto3"
+
+var (
+	file_control_plane_proto_rawDescOnce sync.Once
+	file_control_plane_proto_rawDescData []byte
+)
+
+func file_control_plane_proto_rawDescGZIP() []byte {
+	file_control_plane_proto_rawDescOnce.Do(func() {
+		file_control_plane_proto_rawDescData = protoimpl.X.CompressGZIP(unsafe.Slice(unsafe.StringData(file_control_plane_proto_rawDesc), len(file_control_plane_proto_rawDesc)))
+	})
+	return file_control_plane_proto_rawDescData
+}
+
+var file_control_plane_proto_msgTypes = make([]protoimpl.MessageInfo, 8)
+var file_control_plane_proto_goTypes = []any{
+	(*Empty)(nil),              // 0: messages.Empty
+	(*PingReply)(nil),          // 1: messages.PingReply
+	(*NegotiateRequest)(nil),   // 2: messages.NegotiateRequest
+	(*NegotiateReply)(nil),     // 3: messages.NegotiateReply
+	(*CartIdsReply)(nil),       // 4: messages.CartIdsReply
+	(*OwnerChangeRequest)(nil), // 5: messages.OwnerChangeRequest
+	(*OwnerChangeAck)(nil),     // 6: messages.OwnerChangeAck
+	(*ClosingNotice)(nil),      // 7: messages.ClosingNotice
+}
+var file_control_plane_proto_depIdxs = []int32{
+	0, // 0: messages.ControlPlane.Ping:input_type -> messages.Empty
+	2, // 1: messages.ControlPlane.Negotiate:input_type -> messages.NegotiateRequest
+	0, // 2: messages.ControlPlane.GetCartIds:input_type -> messages.Empty
+	5, // 3: messages.ControlPlane.ConfirmOwner:input_type -> messages.OwnerChangeRequest
+	7, // 4: messages.ControlPlane.Closing:input_type -> messages.ClosingNotice
+	1, // 5: messages.ControlPlane.Ping:output_type -> messages.PingReply
+	3, // 6: messages.ControlPlane.Negotiate:output_type -> messages.NegotiateReply
+	4, // 7: messages.ControlPlane.GetCartIds:output_type -> messages.CartIdsReply
+	6, // 8: messages.ControlPlane.ConfirmOwner:output_type -> messages.OwnerChangeAck
+	6, // 9: messages.ControlPlane.Closing:output_type -> messages.OwnerChangeAck
+	5, // [5:10] is the sub-list for method output_type
+	0, // [0:5] is the sub-list for method input_type
+	0, // [0:0] is the sub-list for extension type_name
+	0, // [0:0] is the sub-list for extension extendee
+	0, // [0:0] is the sub-list for field type_name
+}
+
+func init() { file_control_plane_proto_init() }
+func file_control_plane_proto_init() {
+	if File_control_plane_proto != nil {
+		return
+	}
+	type x struct{}
+	out := protoimpl.TypeBuilder{
+		File: protoimpl.DescBuilder{
+			GoPackagePath: reflect.TypeOf(x{}).PkgPath(),
+			RawDescriptor: unsafe.Slice(unsafe.StringData(file_control_plane_proto_rawDesc), len(file_control_plane_proto_rawDesc)),
+			NumEnums:      0,
+			NumMessages:   8,
+			NumExtensions: 0,
+			NumServices:   1,
+		},
+		GoTypes:           file_control_plane_proto_goTypes,
+		DependencyIndexes: file_control_plane_proto_depIdxs,
+		MessageInfos:      file_control_plane_proto_msgTypes,
+	}.Build()
+	File_control_plane_proto = out.File
+	file_control_plane_proto_goTypes = nil
+	file_control_plane_proto_depIdxs = nil
+}

proto/control_plane.proto

@@ -0,0 +1,89 @@
+syntax = "proto3";
+
+package messages;
+
+option go_package = ".;messages";
+
+// -----------------------------------------------------------------------------
+// Control Plane gRPC API
+// -----------------------------------------------------------------------------
+// Replaces the legacy custom frame-based control channel (previously port 1338).
+// Responsibilities:
+//   - Liveness (Ping)
+//   - Membership negotiation (Negotiate)
+//   - Cart ownership change propagation (ConfirmOwner)
+//   - Cart ID listing for remote grain spawning (GetCartIds)
+//   - Graceful shutdown notifications (Closing)
+// No authentication / TLS is defined initially (can be added later).
+// -----------------------------------------------------------------------------
+
+// Empty request placeholder (common pattern).
+message Empty {}
+
+// Ping reply includes responding host and its current unix time (seconds).
+message PingReply {
+  string host = 1;
+  int64 unix_time = 2;
+}
+
+// NegotiateRequest carries the caller's full view of known hosts (including self).
+message NegotiateRequest {
+  repeated string known_hosts = 1;
+}
+
+// NegotiateReply returns the callee's healthy hosts (including itself).
+message NegotiateReply {
+  repeated string hosts = 1;
+}
+
+// CartIdsReply returns the list of cart IDs (string form) currently owned locally.
+message CartIdsReply {
+  repeated string cart_ids = 1;
+}
+
+// OwnerChangeRequest notifies peers that ownership of a cart moved (or is moving) to new_host.
+message OwnerChangeRequest {
+  string cart_id = 1;
+  string new_host = 2;
+}
+
+// OwnerChangeAck indicates acceptance or rejection of an ownership change.
+message OwnerChangeAck {
+  bool accepted = 1;
+  string message = 2;
+}
+
+// ClosingNotice notifies peers this host is terminating (so they can drop / re-resolve).
+message ClosingNotice {
+  string host = 1;
+}
+
+// ControlPlane defines cluster coordination and ownership operations.
+service ControlPlane {
+  // Ping for liveness; lightweight health signal.
+  rpc Ping(Empty) returns (PingReply);
+
+  // Negotiate merges host views; used during discovery & convergence.
+  rpc Negotiate(NegotiateRequest) returns (NegotiateReply);
+
+  // GetCartIds lists currently owned cart IDs on this node.
+  rpc GetCartIds(Empty) returns (CartIdsReply);
+
+  // ConfirmOwner announces/asks peers to acknowledge ownership transfer.
+  rpc ConfirmOwner(OwnerChangeRequest) returns (OwnerChangeAck);
+
+  // Closing announces graceful shutdown so peers can proactively adjust.
+  rpc Closing(ClosingNotice) returns (OwnerChangeAck);
+}
+
+// -----------------------------------------------------------------------------
+// Generation Instructions:
+// protoc --go_out=. --go_opt=paths=source_relative \
+//        --go-grpc_out=. --go-grpc_opt=paths=source_relative \
+//        control_plane.proto
+//
+// Future Enhancements:
+//  - Add a streaming membership watch (server -> client) for immediate updates.
+//  - Add TLS / mTLS for secure intra-cluster communication.
+//  - Add richer health metadata (load, grain count) in PingReply.
+// -----------------------------------------------------------------------------

proto/control_plane_grpc.pb.go

@@ -0,0 +1,287 @@
+// Code generated by protoc-gen-go-grpc. DO NOT EDIT.
+// versions:
+// - protoc-gen-go-grpc v1.5.1
+// - protoc             v3.21.12
+// source: control_plane.proto
+
+package messages
+
+import (
+	context "context"
+	grpc "google.golang.org/grpc"
+	codes "google.golang.org/grpc/codes"
+	status "google.golang.org/grpc/status"
+)
+
+// This is a compile-time assertion to ensure that this generated file
+// is compatible with the grpc package it is being compiled against.
+// Requires gRPC-Go v1.64.0 or later.
+const _ = grpc.SupportPackageIsVersion9
+
+const (
+	ControlPlane_Ping_FullMethodName         = "/messages.ControlPlane/Ping"
+	ControlPlane_Negotiate_FullMethodName    = "/messages.ControlPlane/Negotiate"
+	ControlPlane_GetCartIds_FullMethodName   = "/messages.ControlPlane/GetCartIds"
+	ControlPlane_ConfirmOwner_FullMethodName = "/messages.ControlPlane/ConfirmOwner"
+	ControlPlane_Closing_FullMethodName      = "/messages.ControlPlane/Closing"
+)
+
+// ControlPlaneClient is the client API for ControlPlane service.
+//
+// For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream.
+//
+// ControlPlane defines cluster coordination and ownership operations.
+type ControlPlaneClient interface {
+	// Ping for liveness; lightweight health signal.
+	Ping(ctx context.Context, in *Empty, opts ...grpc.CallOption) (*PingReply, error)
+	// Negotiate merges host views; used during discovery & convergence.
+	Negotiate(ctx context.Context, in *NegotiateRequest, opts ...grpc.CallOption) (*NegotiateReply, error)
+	// GetCartIds lists currently owned cart IDs on this node.
+	GetCartIds(ctx context.Context, in *Empty, opts ...grpc.CallOption) (*CartIdsReply, error)
+	// ConfirmOwner announces/asks peers to acknowledge ownership transfer.
+	ConfirmOwner(ctx context.Context, in *OwnerChangeRequest, opts ...grpc.CallOption) (*OwnerChangeAck, error)
+	// Closing announces graceful shutdown so peers can proactively adjust.
+	Closing(ctx context.Context, in *ClosingNotice, opts ...grpc.CallOption) (*OwnerChangeAck, error)
+}
+
+type controlPlaneClient struct {
+	cc grpc.ClientConnInterface
+}
+
+func NewControlPlaneClient(cc grpc.ClientConnInterface) ControlPlaneClient {
+	return &controlPlaneClient{cc}
+}
+
+func (c *controlPlaneClient) Ping(ctx context.Context, in *Empty, opts ...grpc.CallOption) (*PingReply, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(PingReply)
+	err := c.cc.Invoke(ctx, ControlPlane_Ping_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func (c *controlPlaneClient) Negotiate(ctx context.Context, in *NegotiateRequest, opts ...grpc.CallOption) (*NegotiateReply, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(NegotiateReply)
+	err := c.cc.Invoke(ctx, ControlPlane_Negotiate_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func (c *controlPlaneClient) GetCartIds(ctx context.Context, in *Empty, opts ...grpc.CallOption) (*CartIdsReply, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(CartIdsReply)
+	err := c.cc.Invoke(ctx, ControlPlane_GetCartIds_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func (c *controlPlaneClient) ConfirmOwner(ctx context.Context, in *OwnerChangeRequest, opts ...grpc.CallOption) (*OwnerChangeAck, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(OwnerChangeAck)
+	err := c.cc.Invoke(ctx, ControlPlane_ConfirmOwner_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func (c *controlPlaneClient) Closing(ctx context.Context, in *ClosingNotice, opts ...grpc.CallOption) (*OwnerChangeAck, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(OwnerChangeAck)
+	err := c.cc.Invoke(ctx, ControlPlane_Closing_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+// ControlPlaneServer is the server API for ControlPlane service.
+// All implementations must embed UnimplementedControlPlaneServer
+// for forward compatibility.
+//
+// ControlPlane defines cluster coordination and ownership operations.
+type ControlPlaneServer interface {
+	// Ping for liveness; lightweight health signal.
+	Ping(context.Context, *Empty) (*PingReply, error)
+	// Negotiate merges host views; used during discovery & convergence.
+	Negotiate(context.Context, *NegotiateRequest) (*NegotiateReply, error)
+	// GetCartIds lists currently owned cart IDs on this node.
+	GetCartIds(context.Context, *Empty) (*CartIdsReply, error)
+	// ConfirmOwner announces/asks peers to acknowledge ownership transfer.
+	ConfirmOwner(context.Context, *OwnerChangeRequest) (*OwnerChangeAck, error)
+	// Closing announces graceful shutdown so peers can proactively adjust.
+	Closing(context.Context, *ClosingNotice) (*OwnerChangeAck, error)
+	mustEmbedUnimplementedControlPlaneServer()
+}
+
+// UnimplementedControlPlaneServer must be embedded to have
+// forward compatible implementations.
+//
+// NOTE: this should be embedded by value instead of pointer to avoid a nil
+// pointer dereference when methods are called.
+type UnimplementedControlPlaneServer struct{}
+
+func (UnimplementedControlPlaneServer) Ping(context.Context, *Empty) (*PingReply, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method Ping not implemented")
+}
+func (UnimplementedControlPlaneServer) Negotiate(context.Context, *NegotiateRequest) (*NegotiateReply, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method Negotiate not implemented")
+}
+func (UnimplementedControlPlaneServer) GetCartIds(context.Context, *Empty) (*CartIdsReply, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method GetCartIds not implemented")
+}
+func (UnimplementedControlPlaneServer) ConfirmOwner(context.Context, *OwnerChangeRequest) (*OwnerChangeAck, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method ConfirmOwner not implemented")
+}
+func (UnimplementedControlPlaneServer) Closing(context.Context, *ClosingNotice) (*OwnerChangeAck, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method Closing not implemented")
+}
+func (UnimplementedControlPlaneServer) mustEmbedUnimplementedControlPlaneServer() {}
+func (UnimplementedControlPlaneServer) testEmbeddedByValue()                      {}
+
+// UnsafeControlPlaneServer may be embedded to opt out of forward compatibility for this service.
+// Use of this interface is not recommended, as added methods to ControlPlaneServer will
+// result in compilation errors.
+type UnsafeControlPlaneServer interface {
+	mustEmbedUnimplementedControlPlaneServer()
+}
+
+func RegisterControlPlaneServer(s grpc.ServiceRegistrar, srv ControlPlaneServer) {
+	// If the following call pancis, it indicates UnimplementedControlPlaneServer was
+	// embedded by pointer and is nil.  This will cause panics if an
+	// unimplemented method is ever invoked, so we test this at initialization
+	// time to prevent it from happening at runtime later due to I/O.
+	if t, ok := srv.(interface{ testEmbeddedByValue() }); ok {
+		t.testEmbeddedByValue()
+	}
+	s.RegisterService(&ControlPlane_ServiceDesc, srv)
+}
+
+func _ControlPlane_Ping_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(Empty)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(ControlPlaneServer).Ping(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: ControlPlane_Ping_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(ControlPlaneServer).Ping(ctx, req.(*Empty))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+func _ControlPlane_Negotiate_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(NegotiateRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(ControlPlaneServer).Negotiate(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: ControlPlane_Negotiate_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(ControlPlaneServer).Negotiate(ctx, req.(*NegotiateRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+func _ControlPlane_GetCartIds_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(Empty)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(ControlPlaneServer).GetCartIds(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: ControlPlane_GetCartIds_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(ControlPlaneServer).GetCartIds(ctx, req.(*Empty))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+func _ControlPlane_ConfirmOwner_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(OwnerChangeRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(ControlPlaneServer).ConfirmOwner(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: ControlPlane_ConfirmOwner_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(ControlPlaneServer).ConfirmOwner(ctx, req.(*OwnerChangeRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+func _ControlPlane_Closing_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(ClosingNotice)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(ControlPlaneServer).Closing(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: ControlPlane_Closing_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(ControlPlaneServer).Closing(ctx, req.(*ClosingNotice))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+// ControlPlane_ServiceDesc is the grpc.ServiceDesc for ControlPlane service.
+// It's only intended for direct use with grpc.RegisterService,
+// and not to be introspected or modified (even as a copy)
+var ControlPlane_ServiceDesc = grpc.ServiceDesc{
+	ServiceName: "messages.ControlPlane",
+	HandlerType: (*ControlPlaneServer)(nil),
+	Methods: []grpc.MethodDesc{
+		{
+			MethodName: "Ping",
+			Handler:    _ControlPlane_Ping_Handler,
+		},
+		{
+			MethodName: "Negotiate",
+			Handler:    _ControlPlane_Negotiate_Handler,
+		},
+		{
+			MethodName: "GetCartIds",
+			Handler:    _ControlPlane_GetCartIds_Handler,
+		},
+		{
+			MethodName: "ConfirmOwner",
+			Handler:    _ControlPlane_ConfirmOwner_Handler,
+		},
+		{
+			MethodName: "Closing",
+			Handler:    _ControlPlane_Closing_Handler,
+		},
+	},
+	Streams:  []grpc.StreamDesc{},
+	Metadata: "control_plane.proto",
+}