skills golang

skills.md

name

gcp-go-event-driven-microservice

description

Design, review, modernize, or scaffold production-ready Go microservices on Google Cloud using net/http, Pub/Sub pull or push delivery, Secret Manager, bounded goroutine worker pools, context propagation, configurable record chunks, graceful shutdown, and optional data adapters. Use when working on Go event-driven services for Cloud Run or GKE, implementing parallel batch processing, fixing Pub/Sub ack/nack behavior, or creating a new GCP microservice.

GCP Go Event-Driven Microservice

Build services that are explicit about ownership, cancellation, delivery semantics, and resource limits. Treat golang-standards/project-layout as a useful reference, not an official Go standard.

Workflow

1. Inspect go.mod, entrypoints, configuration, event contracts, repositories, deployment files, and tests before proposing changes.
2. Verify the current stable Go release from https://go.dev/dl/?mode=json; do not rely on a version embedded in this skill.
3. Choose Pub/Sub pull, push, or both. Keep business processing independent from transport handlers.
4. Define event identity, validation, retry classification, idempotency boundary, chunk source, and maximum concurrency.
5. Propagate context.Context from transport to every blocking operation. Never store a request context in a struct.
6. Process records with bounded concurrency. Prefer errgroup.WithContext, SetLimit, and immutable chunk ownership.
7. Ack only after the complete job succeeds. Nack transient pull failures; return a retryable HTTP status for transient push failures. Ack or return success for explicitly handled permanent failures to prevent poison loops.
8. Add graceful shutdown, readiness, structured logs, traces, and metrics before declaring the service production-ready.
9. Run go mod tidy, go test ./..., go test -race ./..., and go vet ./....

Scaffold A Service

Copy a configuration, adjust it, and run the bundled generator:

cp assets/example-config.json /tmp/microservice.json
python3 scripts/scaffold.py --config /tmp/microservice.json --output ./orders-service

The generator queries the official Go downloads endpoint and runs go get module@latest for only the selected adapters. Use --skip-dependency-resolution only for offline inspection; the resulting module will require go mod tidy later.

Non-Negotiable Rules

• Default CHUNK_SIZE to 500 and MAX_WORKERS to min(GOMAXPROCS, 8) when unset.
• Bound Pub/Sub receive concurrency separately from per-message chunk workers to avoid multiplicative overload.
• Cancel sibling work on the first non-recoverable chunk error.
• Recover panics at goroutine boundaries and convert them to errors with stack context.
• Do not mutate shared slices or maps from workers. Give each worker an exclusive chunk and aggregate results after completion.
• Require idempotent processing because Pub/Sub is at-least-once delivery.
• Never hardcode project IDs, credentials, topic names, subscription names, or database DSNs.
• Keep optional adapters out of source and go.mod unless selected.
• Prefer the standard library; add a dependency only when it removes meaningful risk or boilerplate.

Read References Selectively

• Read architecture.md when designing package boundaries, startup, or deployment.
• Read concurrency-and-chunks.md when implementing goroutines, chunk workers, cancellation, or backpressure.
• Read pubsub-delivery.md when implementing pull/push handlers, retries, ordering, or idempotency.
• Read configuration-and-adapters.md when adding environment variables, Secret Manager, databases, Redis, Firestore, or Storage.
• Read testing-and-operations.md for tests, observability, rollout, and production checks.

Review Output

When reviewing an existing service, report findings in this order:

1. Delivery correctness: premature ack, poison-message loops, duplicate effects.
2. Concurrency safety: unbounded goroutines, leaks, races, blocked shutdown.
3. Context correctness: lost cancellation, missing deadlines, background contexts in request paths.
4. Resource safety: connection lifecycle, receiver limits, chunk sizing, memory pressure.
5. Operability: readiness, metrics, tracing, structured logs, deployment identity.

Provide concrete file references and focused remediation. Do not force the starter layout onto a healthy existing codebase.