Using ColdBrew

Table of contents

1. Project Structure
2. Defining Your API
3. Implementing Your Service
4. Running Your Service
5. Configuration
6. Adding Interceptors
7. What’s Next?

This guide covers how to use ColdBrew after you have created a project. If you haven’t created a project yet, see the Getting Started guide.

Project Structure

A ColdBrew project generated from the cookiecutter template has the following structure:

MyApp/
  proto/              # Protocol buffer definitions
    helloworld.proto
  server/             # gRPC service implementation
    server.go
  main.go             # Entry point
  Makefile             # Build, test, lint, run targets
  Dockerfile           # Production container
  go.mod

Defining Your API

ColdBrew services are defined using Protocol Buffers. Edit your .proto file to add new RPC methods:

service MySvc {
  rpc SayHello (SayHelloRequest) returns (SayHelloResponse) {
    option (google.api.http) = {
      get: "/api/v1/hello"
    };
  }
}

The google.api.http annotation automatically creates a REST endpoint via grpc-gateway.

After editing your proto file, regenerate the Go code:

make gen

Implementing Your Service

Implement the generated gRPC interface in your server/server.go:

func (s *svcNameImpl) SayHello(ctx context.Context, req *pb.SayHelloRequest) (*pb.SayHelloResponse, error) {
    return &pb.SayHelloResponse{
        Message: "Hello " + req.GetName(),
    }, nil
}

Your service struct implements core.CBService, which requires two methods:

• InitHTTP(ctx context.Context, mux *runtime.ServeMux, endpoint string, opts []grpc.DialOption) — Registers HTTP/REST handlers
• InitGRPC(ctx context.Context, s *grpc.Server) — Registers gRPC handlers

Running Your Service

make run

This starts the service with:

• gRPC server on port 9090 (default)
• HTTP gateway on port 9091 (default)
• Prometheus metrics at /metrics
• Health check at /healthcheck and /readycheck
• pprof debug endpoints at /debug/pprof/

Configuration

ColdBrew uses environment variables for configuration. Common settings:

Adding Interceptors

ColdBrew comes with a comprehensive set of interceptors pre-configured. To add custom interceptors:

import "github.com/go-coldbrew/interceptors"

func init() {
    interceptors.AddUnaryServerInterceptor(myCustomInterceptor)
}

Interceptor configuration functions must be called during init() — they are not safe for concurrent use.

What’s Next?

• How-To Guides — Detailed guides for tracing, logging, metrics, error handling, and more
• Integrations — Setting up New Relic, Prometheus, Sentry, and other integrations
• Packages — Browse all ColdBrew packages