Cursor Rules Template: Apache Pulsar Go Client Subscriber

Overview

The Cursor rules configuration for this page defines how Cursor AI should assist Go developers implementing an Apache Pulsar Go client subscriber. It covers the Pulsar Go client stack, including subscriber lifecycle, message processing, error handling, and production readiness.

When to Use These Cursor Rules

• When building a message consumer using the Pulsar Go client in a Go project.
• When you want Cursor AI to enforce safe patterns around Receive loops and ack/nack semantics.
• When you need a copyable .cursorrules configuration tailored for a Pulsar subscriber service.

Copyable .cursorrules Configuration

# Cursor Rules for Pulsar Go Client Subscriber
frameworkRole: Go developer assistant for Apache Pulsar
frameworkContext: Go module using Pulsar Go client v1.x; subscriber pattern
codeStyle: gofmt; golangci-lint; idiomatic error handling with errors.Is and wrap
architectureDirectoryRules:
  - internal/pulsar/subscriber
  - pkg/pulsar
  - config
authenticationSecurity:
  - use TLS with mTLS if available
  - credentials via environment variables; do not hardcode secrets
  - rotate tokens; do not log secrets in production
databaseAndOrm:
  - Pulsar is the messaging backbone; no ORM usage for messages
  - store message metadata in internal/cache or a DB only if needed for audits
testingAndLinting:
  - unit tests for message handler;
  - integration tests against a Pulsar test instance;
  - CI runs go test ./... and golangci-lint run
prohibitedActions:
  - do not bypass TLS; avoid insecure endpoints
  - do not embed credentials in code
  - do not swallow errors; always return or log with context

Recommended Project Structure

myapp/
├── go.mod
├── cmd/
│   └── app/
│       └── main.go
├── internal/
│   └── pulsar/
│       └── subscriber/
│           ├── consumer.go
│           └── subscriber.go
├── pkg/
│   └── pulsar/
│       └── client.go
├── config/
│   └── config.go
├── tests/
│   └── pulsar_integration_test.go

Core Engineering Principles

• Single Responsibility: each package handles a focused concern (subscriber logic, Pulsar client wrapper, config).
• Explicit error handling: propagate errors with context; do not ignore failures.
• Config as code: env-driven, deterministic defaults, no magic values.
• Observability: structured logs, metrics for message latency and backoffs.
• Security by default: TLS, credential management, secret rotation.
• Testability: unit and integration tests; easy local Pulsar runs.

Code Construction Rules

• Client initialization: use pulsar.NewClient with TLS and proper URL; respect timeouts and context.
• Subscriber creation: create a dedicated consumer with subscription name; set ReceiverQueueSize for backpressure.
• Message processing: acknowledge on success; use Nack or Redeliver on failure; ensure at-most-once or at-least-once semantics are explicit.
• Context management: cancel context on shutdown; use context.WithCancel in main flow.
• Error handling: wrap errors with operation context; do not log sensitive data.
• Testing: mock Pulsar when possible; run integration tests against a real Pulsar instance in CI.
• Performance: avoid blocking calls; use channels and timeouts to prevent goroutine leaks.

Security and Production Rules

• Enable TLS; verify certificates; disable insecure endpoints.
• Store credentials in environment or secret manager; rotate tokens; remove from code.
• Limit access to Pulsar brokers; use network policies and mTLS if supported.
• Observability: structured logs, tracing where possible; avoid leaking secrets in logs.
• Deployment hygiene: CI checks, go vet, go fmt, and go test gates before merge.

Testing Checklist

• Unit tests for the message handler; mock Pulsar client interfaces.
• Integration tests with a Pulsar test instance; verify ack/nack paths and redelivery.
• End-to-end tests for the consumer workflow; simulate message processing errors.
• Linting and formatting: golangci-lint; go fmt; static analysis.
• CI/CD: run tests, lint, build artifacts for release.

Common Mistakes to Avoid

• Assuming at-least-once guarantees without proper idempotency in handlers.
• Ignoring backpressure; using blocking loops that stall the processor.
• Hardcoding credentials or endpoints in code.
• Over-complicating the consumer with unnecessary retry loops without backoff.

FAQ

What is this Cursor Rules Template for Apache Pulsar Go Client Subscriber?

It provides a copyable .cursorrules configuration and coding guidance to implement a Pulsar subscriber in Go, with Cursor AI rules to enforce best practices, security, and testability.

Which stack does this template cover?

Go language with the official Pulsar Go client, focused on a subscriber/consumer pattern and production-grade patterns, including TLS and token-based authentication.

How do I apply the .cursorrules block?

Paste the code block into the project root as .cursorrules; Cursor AI reads it to shape development and reviews.

What security concerns are addressed?

TLS, token-based credentials, and environment-based configuration; no secrets in code; rotation and auditing are enforced by the rules.

How is testing handled?

Includes unit tests for handlers and integration tests against a Pulsar instance; CI gated checks, linting, and reproducible test environments are recommended.