51 lines
3.1 KiB
Markdown
51 lines
3.1 KiB
Markdown
# GitHub Copilot Instructions for Go Cart Actor
|
|
|
|
This repository contains a distributed cart management system implemented in Go using the actor model pattern. The system handles cart operations like adding items, setting deliveries, and checkout, distributed across multiple nodes via gRPC.
|
|
|
|
## Project Structure
|
|
- `cmd/`: Entry points for the application.
|
|
- `pkg/`: Core packages including grain logic, pools, and HTTP handlers.
|
|
- `proto/`: Protocol Buffer definitions for messages and services.
|
|
- `api-tests/`: Tests for the HTTP API.
|
|
- `deployment/`: Deployment configurations.
|
|
- `k6/`: Load testing scripts.
|
|
|
|
## Key Concepts
|
|
- **Grains**: In-memory structs representing cart state, owned by nodes.
|
|
- **Pools**: Local and synced pools manage grains and handle ownership.
|
|
- **Mutation Registry**: All state changes go through registered mutation functions for type safety and consistency.
|
|
- **Ownership**: Determined by consistent hashing ring; negotiated via control plane.
|
|
|
|
## Coding Guidelines
|
|
- Follow standard Go conventions (gofmt, go vet, golint).
|
|
- Never say "your right", just be correct and clear.
|
|
- Don't edit the *.gb.go files manually, they are generated by the proto files.
|
|
- Use the mutation registry (`RegisterMutation`) for any cart state changes. Do not mutate grain state directly outside registered handlers.
|
|
- Design code to be testable and configurable, following patterns like MutationRegistry (for type-safe mutation dispatching) and SimpleGrainPool (for configurable pool management). Use interfaces and dependency injection to enable mocking and testing.
|
|
- After modifying `.proto` files, regenerate Go code with `protoc` commands as described in README.md. Never edit generated `.pb.go` files manually.
|
|
- Use meaningful variable names and add comments for complex logic.
|
|
- Handle errors explicitly; use Go's error handling patterns.
|
|
- For HTTP endpoints, ensure proper cookie handling for cart IDs.
|
|
- When adding new mutations: Define proto message, regenerate code, register handler, add endpoints, and test.
|
|
- Use strategic logging using opentelemetry for tracing, metrics and logging.
|
|
- Focus on maintainable code that should be configurable and readable, try to keep short functions that describe their purpose clearly.
|
|
|
|
## Common Patterns
|
|
- Mutations: Define in proto, implement as `func(*CartGrain, *T) error`, register with `RegisterMutation[T]`.
|
|
- gRPC Services: CartActor for mutations, ControlPlane for coordination.
|
|
- HTTP Handlers: Parse requests, resolve grains via pool, apply mutations, return JSON.
|
|
|
|
## Avoid
|
|
- Direct state mutations outside the registry.
|
|
- Hardcoding values; use configuration or constants.
|
|
- Ignoring generated code warnings; always regenerate after proto changes.
|
|
- Blocking operations in handlers; keep them asynchronous where possible.
|
|
|
|
## Testing
|
|
- Write unit tests for mutations and handlers.
|
|
- Use integration tests for API endpoints.
|
|
- Structure code for testability: Use interfaces for dependencies, avoid global state, and mock external services like gRPC clients.
|
|
- Run `go test ./...` to ensure all tests pass.
|
|
|
|
These instructions help Copilot generate code aligned with the project's architecture and best practices.
|