go-cart-actor/README.md

Go Cart Actor

A distributed cart management system using the actor model pattern.

Prerequisites

• Go 1.24.2+
• Protocol Buffers compiler (protoc)
• protoc-gen-go and protoc-gen-go-grpc plugins

Installing Protocol Buffers

On Windows:

winget install protobuf

On macOS:

brew install protobuf

On Linux:

# Ubuntu/Debian
sudo apt install protobuf-compiler

# Or download from: https://github.com/protocolbuffers/protobuf/releases

Installing Go protobuf plugin

go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

Working with Protocol Buffers

Generating Go code from proto files

After modifying any proto (proto/messages.proto, proto/cart_actor.proto, proto/control_plane.proto), regenerate the Go code (all three share the unified messages package):

cd proto
protoc --go_out=. --go_opt=paths=source_relative \
       --go-grpc_out=. --go-grpc_opt=paths=source_relative \
       messages.proto cart_actor.proto control_plane.proto

Protocol Buffer Messages

The proto/messages.proto file defines the following message types:

• AddRequest - Add items to cart (includes quantity, sku, country, optional storeId)
• SetCartRequest - Set entire cart contents
• AddItem - Complete item information for cart
• RemoveItem - Remove item from cart
• ChangeQuantity - Update item quantity
• SetDelivery - Configure delivery options
• SetPickupPoint - Set pickup location
• PickupPoint - Pickup point details
• RemoveDelivery - Remove delivery option
• CreateCheckoutOrder - Initiate checkout
• OrderCreated - Order creation response

Building the project

go build .

Running tests

go test ./...

HTTP API Quick Start (curl Examples)

Assuming the service is reachable at http://localhost:8080 and the cart API is mounted at /cart. Most endpoints use an HTTP cookie named cartid to track the cart. The first request will set it.

1. Get (or create) a cart

curl -i http://localhost:8080/cart/

Response sets a cartid cookie and returns the current (possibly empty) cart JSON.

2. Add an item by SKU (implicit quantity = 1)

curl -i --cookie-jar cookies.txt http://localhost:8080/cart/add/TEST-SKU-123

Stores cookie in cookies.txt for subsequent calls.

3. Add an item with explicit payload (country, quantity)

curl -i --cookie cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"sku":"TEST-SKU-456","quantity":2,"country":"se"}' \
  http://localhost:8080/cart/

4. Change quantity of an existing line

(First list the cart to find id of the line; here we use id=1 as an example)

curl -i --cookie cookies.txt \
  -X PUT -H "Content-Type: application/json" \
  -d '{"id":1,"quantity":3}' \
  http://localhost:8080/cart/

5. Remove an item

curl -i --cookie cookies.txt -X DELETE http://localhost:8080/cart/1

6. Set entire cart contents (overwrites items)

curl -i --cookie cookies.txt \
  -X POST -H "Content-Type: application/json" \
  -d '{"items":[{"sku":"TEST-SKU-AAA","quantity":1,"country":"se"},{"sku":"TEST-SKU-BBB","quantity":2,"country":"se"}]}' \
  http://localhost:8080/cart/set

7. Add a delivery (provider + optional items)

If items is empty or omitted, all items without a delivery get this one.

curl -i --cookie cookies.txt \
  -X POST -H "Content-Type: application/json" \
  -d '{"provider":"standard","items":[1,2]}' \
  http://localhost:8080/cart/delivery

8. Remove a delivery by deliveryId

curl -i --cookie cookies.txt -X DELETE http://localhost:8080/cart/delivery/1

9. Set a pickup point for a delivery

curl -i --cookie cookies.txt \
  -X PUT -H "Content-Type: application/json" \
  -d '{"id":"PUP123","name":"Locker 5","address":"Main St 1","city":"Stockholm","zip":"11122","country":"SE"}' \
  http://localhost:8080/cart/delivery/1/pickupPoint

10. Checkout (returns HTML snippet from Klarna)

curl -i --cookie cookies.txt http://localhost:8080/cart/checkout

11. Using a known cart id directly (bypassing cookie)

If you already have a cart id (e.g. 1720000000000000):

CART_ID=1720000000000000
curl -i http://localhost:8080/cart/byid/$CART_ID
curl -i -X POST -H "Content-Type: application/json" \
  -d '{"sku":"TEST-SKU-XYZ","quantity":1,"country":"se"}' \
  http://localhost:8080/cart/byid/$CART_ID

12. Clear cart cookie (forces a new cart on next request)

curl -i --cookie cookies.txt -X DELETE http://localhost:8080/cart/

Tip: Use --cookie-jar and --cookie to persist the session across multiple commands:

curl --cookie-jar cookies.txt http://localhost:8080/cart/
curl --cookie cookies.txt http://localhost:8080/cart/add/TEST-SKU-123

Important Notes

• Always regenerate protobuf Go code after modifying any .proto files (messages/cart_actor/control_plane)
• The generated messages.pb.go file should not be edited manually
• Make sure your PATH includes the protoc-gen-go binary location (usually $GOPATH/bin)