Docs overhaul: cleanup, fixes, and improvements

FAQ.md

@@ -128,10 +128,12 @@ You can register cleanup callbacks and customize shutdown behavior. See the [Sig
 Set the `SENTRY_DSN` environment variable and use the errors package:
 
 ```go
-import "github.com/go-coldbrew/errors"
+import (
+    "github.com/go-coldbrew/errors/notifier"
+)
 
 // This notifies Sentry asynchronously (bounded, won't leak goroutines)
-errors.NotifyAsync(err, severity, args...)
+notifier.Notify(err, ctx)
 ```
 
 See the [Errors How-To](/howto/errors) and [Integrations](/integrations) for full setup instructions.

Index.md

@@ -55,8 +55,8 @@ Your service starts with all of these endpoints ready:
 | `localhost:9090` | gRPC server |
 | `localhost:9091` | HTTP/REST gateway (auto-mapped from gRPC) |
 | `localhost:9091/metrics` | Prometheus metrics |
-| `localhost:9091/healthcheck` | Kubernetes liveness probe |
-| `localhost:9091/readycheck` | Kubernetes readiness probe |
+| `localhost:9091/healthcheck` | Liveness probe — returns build/version info as JSON |
+| `localhost:9091/readycheck` | Readiness probe — returns version JSON when ready |
 | `localhost:9091/swagger/` | Swagger UI |
 | `localhost:9091/debug/pprof/` | Go pprof profiling |
 

Packages.md

@@ -3,6 +3,7 @@ layout: default
 title: Packages
 description: "ColdBrew packages documentation"
 permalink: /packages
+nav_order: 9
 ---
 # Packages
 {: .no_toc }
@@ -19,7 +20,7 @@ The core module is the base module and provides the base implementation for Cold
 Documentation can be found at [core-docs]
 
 ### [Config]
-Coldbrew config package contains the configuration for the core package. It uses [envconfig] to load the configuration from the environment variables.
+ColdBrew config package contains the configuration for the core package. It uses [envconfig] to load the configuration from the environment variables.
 
 Documentation can be found at [config-docs]
 
@@ -85,3 +86,4 @@ Documentation can be found at [data-builder-docs]
 [grpcpool-docs]: https://pkg.go.dev/github.com/go-coldbrew/grpcpool
 [Data Builder]: https://github.com/go-coldbrew/data-builder/tree/main#readme
 [data-builder-docs]: https://pkg.go.dev/github.com/go-coldbrew/data-builder
+[envconfig]: https://github.com/kelseyhightower/envconfig

USING.md

@@ -23,12 +23,19 @@ A ColdBrew project generated from the [cookiecutter template](https://github.com
 ```
 MyApp/
   proto/              # Protocol buffer definitions
-    helloworld.proto
-  server/             # gRPC service implementation
-    server.go
+    myapp.proto
+  service/            # gRPC service implementation
+    service.go
+    service_test.go
+    healthcheck.go
+    healthcheck_test.go
+  config/
+    config.go         # Configuration via environment variables
+  version/
+    version.go        # Build-time version info
   main.go             # Entry point
-  Makefile             # Build, test, lint, run targets
-  Dockerfile           # Production container
+  Makefile            # Build, test, lint, run targets
+  Dockerfile          # Production container
   go.mod
 ```
 
@@ -51,12 +58,12 @@ The `google.api.http` annotation automatically creates a REST endpoint via grpc-
 After editing your proto file, regenerate the Go code:
 
 ```shell
-make gen
+make generate
 ```
 
 ## Implementing Your Service
 
-Implement the generated gRPC interface in your `server/server.go`:
+Implement the generated gRPC interface in your `service/service.go`:
 
 ```go
 func (s *svcNameImpl) SayHello(ctx context.Context, req *pb.SayHelloRequest) (*pb.SayHelloResponse, error) {

_config.yml

@@ -21,6 +21,8 @@ defaults:
 
 permalink: pretty
 
+search_enabled: true
+
 theme: just-the-docs
 
 callouts_level: quiet

architecture.md

@@ -216,8 +216,9 @@ A typical ColdBrew service exposes two ports:
 
 ColdBrew is designed for Kubernetes deployments:
 
-- **Liveness probe:** `GET /healthcheck` — returns `SERVING` when healthy
-- **Readiness probe:** `GET /readycheck` — returns `SERVING` when ready for traffic
+- **Liveness probe:** `GET /healthcheck` — returns build/version info as JSON (git commit, version, build date, Go version, OS/arch)
+- **Readiness probe:** `GET /readycheck` — returns the same version JSON when ready for traffic, or an error if the service hasn't called `SetReady()` yet
+- **gRPC health protocol:** Implements `grpc.health.v1.Health` ([standard gRPC health checking](https://github.com/grpc/grpc/blob/master/doc/health-checking.md)) on the gRPC port — used by gRPC load balancers, Envoy, Istio, and other service meshes for native health checking
 - **Graceful shutdown:** On SIGTERM, the service marks itself as not ready, drains in-flight requests, then exits cleanly
 - **Metrics scraping:** Prometheus scrapes `/metrics` on the HTTP port
 

data-builder-example/go.mod

@@ -1,6 +1,6 @@
 module example
 
-go 1.19
+go 1.25
 
 require github.com/go-coldbrew/data-builder v0.0.11
 

data-builder-example/go.sum

@@ -151,6 +151,7 @@ github.com/google/go-cmp v0.5.0/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/
 github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
 github.com/google/go-cmp v0.5.6/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
 github.com/google/go-cmp v0.5.9 h1:O2Tfq5qg4qc4AmwVlvv0oLiVAGB7enBSJ2x2DqQFi38=
+github.com/google/go-cmp v0.5.9/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
 github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
 github.com/google/gofuzz v1.1.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
 github.com/google/martian v2.1.0+incompatible/go.mod h1:9I4somxYTbIHy5NJKHRl3wXiIaQGbYVAs8BPL6v8lEs=
@@ -344,6 +345,7 @@ github.com/stretchr/testify v1.4.0/go.mod h1:j7eGeouHqKxXV5pUuKE4zz7dFj8WfuZ+81P
 github.com/stretchr/testify v1.5.1/go.mod h1:5W2xD1RspED5o8YsWQXVCued0rvSQ+mT+I5cxcmMvtA=
 github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.8.2 h1:+h33VjcLVPDHtOdpUCuF+7gSuG3yGIftsP1YvFihtJ8=
+github.com/stretchr/testify v1.8.2/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
 github.com/subosito/gotenv v1.2.0/go.mod h1:N0PQaV/YGNqwC0u51sEeR/aUtSLEXKX9iv69rRypqCw=
 github.com/tmc/grpc-websocket-proxy v0.0.0-20190109142713-0ad062ec5ee5/go.mod h1:ncp9v5uamzpCO7NfCPTXjqaC+bZgJeR0sMTm6dMHP7U=
 github.com/ugorji/go v1.1.4/go.mod h1:uQMGLiO92mf5W77hV/PUCpI3pbzQx3CRekS0kk+RGrc=
@@ -362,6 +364,7 @@ go.opencensus.io v0.22.0/go.mod h1:+kGneAE2xo2IficOXnaByMWTGM9T73dGwxeWcUqIpI8=
 go.opentelemetry.io/proto/otlp v0.7.0/go.mod h1:PqfVotwruBrMGOCsRd/89rSnXhoiJIqeYNgFYFoEGnI=
 go.uber.org/atomic v1.4.0/go.mod h1:gD2HeocX3+yG+ygLZcrzQJaqmWj9AIm7n08wl/qW/PE=
 go.uber.org/goleak v1.1.12 h1:gZAh5/EyT/HQwlpkCy6wTpqfH9H8Lz8zbm3dZh+OyzA=
+go.uber.org/goleak v1.1.12/go.mod h1:cwTWslyiVhfpKIDGSZEM2HlOvcqm+tG4zioyIeLoqMQ=
 go.uber.org/multierr v1.1.0/go.mod h1:wR5kodmAFQ0UK8QlbwjlSNy0Z68gJhDJUG5sjR94q/0=
 go.uber.org/zap v1.10.0/go.mod h1:vwi/ZaCAaUcBkycHslxD9B2zi4UTXhF60s6SWpuDF0Q=
 golang.org/x/crypto v0.0.0-20180904163835-0709b304e793/go.mod h1:6SG95UA2DQfeDnfUPMdvaQW0Q7yPrPDi9nlGo2tz2b4=
@@ -610,6 +613,7 @@ gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C
 gopkg.in/yaml.v3 v3.0.0-20200615113413-eeeca48fe776/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 honnef.co/go/tools v0.0.0-20190102054323-c2f93a96b099/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
 honnef.co/go/tools v0.0.0-20190106161140-3f1c8253044a/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
 honnef.co/go/tools v0.0.0-20190418001031-e561f6794a2a/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=

howto/APIs.md

@@ -11,9 +11,9 @@ parent: "How To"
 
 ## Introduction
 
-Coldbrew is gRPC first, which means that gRPC APIs are the primary APIs and HTTP/JSON APIs are generated from the gRPC APIs. This approach is different from other frameworks where HTTP/JSON APIs are independent from gRPC APIs.
+ColdBrew is gRPC first, which means that gRPC APIs are the primary APIs and HTTP/JSON APIs are generated from the gRPC APIs. This approach is different from other frameworks where HTTP/JSON APIs are independent from gRPC APIs.
 
-Coldbrew uses [grpc-gateway] to generate HTTP/JSON APIs from gRPC APIs. It reads protobuf service definitions and generates a reverse-proxy server which translates a RESTful HTTP API into gRPC. This server is generated according to the [google.api.http annotations] in your service definitions.
+ColdBrew uses [grpc-gateway] to generate HTTP/JSON APIs from gRPC APIs. It reads protobuf service definitions and generates a reverse-proxy server which translates a RESTful HTTP API into gRPC. This server is generated according to the [google.api.http annotations] in your service definitions.
 
 {: .note}
 To learn more about HTTP to gRPC API mapping please refer to [gRPC Gateway mapping] examples.
@@ -47,7 +47,7 @@ message UpperResponse{
 
 The above example adds a new API endpoint to the service which converts the input string to upper case. The endpoint is available at `/api/v1/example/upper` on the HTTP port and `example.v1.MySvc/Upper` on the gRPC port.
 
-Run `make generate` (for [Coldbrew cookiecutter]) or `protoc`/`buf`  with [grpc-gateway plugin] for others to generate the gRPC and HTTP code.
+Run `make generate` (for [ColdBrew cookiecutter]) or `protoc`/`buf`  with [grpc-gateway plugin] for others to generate the gRPC and HTTP code.
 
 In your service implement the gRPC server interface
 
@@ -60,7 +60,7 @@ func (s *svc) Upper(_ context.Context, req *proto.UpperRequest) (*proto.UpperRes
 }
 ```
 
-Run your server (`make run` for [Coldbrew cookiecutter]) and send a request to the HTTP endpoint:
+Run your server (`make run` for [ColdBrew cookiecutter]) and send a request to the HTTP endpoint:
 
 ```bash
 $ curl -X POST -d '{"msg":"hello"}' -i http://localhost:9091/api/v1/example/upper
@@ -84,7 +84,7 @@ $ grpcurl -plaintext -d '{"msg": "hello"}' localhost:9090 example.v1.MySvc/Upper
 
 ## HTTP Content-Type
 
-Coldbrew supports multiple content-types for requests and responses. The default content-type is `application/json`. The following content-types are supported by default:
+ColdBrew supports multiple content-types for requests and responses. The default content-type is `application/json`. The following content-types are supported by default:
 
 - `application/json`
 - `application/proto`
@@ -211,7 +211,7 @@ message Status {
 ```
 ### gRPC status codes and HTTP status codes mapping
 
-gRPC status codes can be easlity translated to HTTP status codes. The following table shows the mapping between the canonical error codes and HTTP status codes:
+gRPC status codes can be easily translated to HTTP status codes. The following table shows the mapping between the canonical error codes and HTTP status codes:
 
 | gRPC status code      | HTTP status code |
 | --------------------  | ---------------- |
@@ -372,9 +372,9 @@ $ curl -X GET localhost:8080/v1/books/
 }
 ```
 
-### Using Coldbrew errors package
+### Using ColdBrew errors package
 
-All the above examples can be used with the [Coldbrew errors package] by using the functions `NewWithStatus/WrapWithStatus`
+All the above examples can be used with the [ColdBrew errors package] by using the functions `NewWithStatus/WrapWithStatus`
 
 ```go
 import (
@@ -399,7 +399,7 @@ func (s *server) GetBook(ctx context.Context, req *pb.GetBookRequest) (*pb.Book,
 
 Using the `errors.WrapWithStatus` function has the same effect as `errors.Wrap` but it also sets the status code of the error to the status code of the `google.rpc.Status` message. Similarly, the `errors.NewWithStatus` function has the same effect as `errors.New` but it also sets the status code of the error to the status code of the `google.rpc.Status` message.
 
-Coldbrew errors package also provides stack trace support for errors, which can make debugging easier. For more information see Coldbrew [errors package].
+ColdBrew errors package also provides stack trace support for errors, which can make debugging easier. For more information see ColdBrew [errors package].
 
 ## Customizing HTTP Error Responses
 
@@ -535,13 +535,13 @@ For more advanced customization options, refer to the [grpc-gateway customizatio
 ---
 [google/rpc/status.proto]: https://github.com/googleapis/googleapis/blob/master/google/rpc/status.proto
 [google/rpc/code.proto]: https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto
-[Coldbrew errors package]: https://pkg.go.dev/github.com/go-coldbrew/errors#NewWithStatus
+[ColdBrew errors package]: https://pkg.go.dev/github.com/go-coldbrew/errors#NewWithStatus
 [errors package]: https://pkg.go.dev/github.com/go-coldbrew/errors
 [envconfig]: https://github.com/kelseyhightower/envconfig
-[Coldbrew]: https://docs.coldbrew.cloud
+[ColdBrew]: https://docs.coldbrew.cloud
 [google.api.http annotations]: https://cloud.google.com/endpoints/docs/grpc/transcoding
 [grpc-gateway]: https://grpc-ecosystem.github.io/grpc-gateway/
 [gRPC Gateway mapping]: https://grpc-ecosystem.github.io/grpc-gateway/docs/mapping/examples/
 [grpc-gateway plugin]: https://grpc-ecosystem.github.io/grpc-gateway/docs/tutorials/generating_stubs/
-[Coldbrew cookiecutter]: /getting-started#using-the-coldbrew-cookiecutter-template
+[ColdBrew cookiecutter]: /getting-started#using-the-coldbrew-cookiecutter-template
 [grpc-gateway customization guide]: https://grpc-ecosystem.github.io/grpc-gateway/docs/mapping/customizing_your_gateway/

howto/Debugging.md

@@ -2,6 +2,7 @@
 layout: default
 title: "Debugging"
 parent: "How To"
+description: "Debugging ColdBrew services with pprof and log overrides"
 ---
 ## Table of contents
 {: .no_toc .text-delta }
@@ -39,7 +40,7 @@ Showing top 5 nodes out of 45
 
 ### Analyzing profiles
 
-The `go tool pprof` command can be  also be used analyze profiles to find the root cause of performance issues. For more information, please refer to the [pprof walkthrough] and the [diagnostics doc].
+The `go tool pprof` command can be  also be used to analyze profiles to find the root cause of performance issues. For more information, please refer to the [pprof walkthrough] and the [diagnostics doc].
 
 {: .important }
 Its recommended that you go though the [pprof walkthrough] to get a better understanding of how to use the pprof.

howto/Log.md

@@ -2,6 +2,7 @@
 layout: default
 title: "Log"
 parent: "How To"
+description: "Context-aware logging and trace ID propagation in ColdBrew"
 ---
 ## Table of contents
 {: .no_toc .text-delta }

howto/Metrics.md

@@ -2,16 +2,17 @@
 layout: default
 title: "Metrics"
 parent: "How To"
+description: "Prometheus metrics and custom metrics in ColdBrew"
 ---
 ## Table of contents
 {: .no_toc .text-delta }
 
 1. TOC
 {:toc}
 
-## How Metrics Work in Coldbrew
+## How Metrics Work in ColdBrew
 
-Coldbrew uses [Prometheus](https://prometheus.io/) to collect service metrics. By Default, Coldbrew will expose a `/metrics` endpoint that will return the metrics in the [Prometheus exposition format](https://prometheus.io/docs/instrumenting/exposition_formats/) on the configured [HTTP port].
+ColdBrew uses [Prometheus](https://prometheus.io/) to collect service metrics. By Default, ColdBrew will expose a `/metrics` endpoint that will return the metrics in the [Prometheus exposition format](https://prometheus.io/docs/instrumenting/exposition_formats/) on the configured [HTTP port].
 
 A collection of metrics are collected by default, including:
 * Golang runtime metrics (e.g. memory usage, goroutine count, etc.)
@@ -45,7 +46,7 @@ func myFunction() {
 }
 ```
 
-These metrics will be automatically collected and exposed by Coldbrew on the `/metrics` endpoint.
+These metrics will be automatically collected and exposed by ColdBrew on the `/metrics` endpoint.
 
 {: .note .note-info }
 To learn more about the Prometheus and the data types it supports, see [here](https://prometheus.io/docs/concepts/metric_types/)

howto/Tracing.md

@@ -11,7 +11,7 @@ parent: "How To"
 
 ## Overview
 
-Coldbrew provides a way to add tracing to your functions using the [go-coldbrew/tracing] package. The Package implements multiple tracing backends (e.g. [New Relic] / [Opentelemetry] / [Jaeger]) which enables you to switch between them without changing your code.
+ColdBrew provides a way to add tracing to your functions using the [go-coldbrew/tracing] package. The Package implements multiple tracing backends (e.g. [New Relic] / [Opentelemetry] / [Jaeger]) which enables you to switch between them without changing your code.
 
 {: .note .note-info }
 Its possible for you to have multiple backends enabled at the same time, for example you can have both [New Relic] and [Opentelemetry] enabled at the same time in the same span and they will both receive the same trace.

howto/data-builder.md

@@ -76,7 +76,7 @@ func BuildAppResponse(_ context.Context, grossPrice GrossPrice, priceAdjustment
 
 Note that the builder function signatures must satisfy the following requirements:
 1. The first argument is a context.Context
-2. All subsequent arguments are stucts
+2. All subsequent arguments are structs
 3. There are two return values: a struct and an error
 
 
@@ -120,7 +120,7 @@ During compilation we resolve all dependencies and build an execution plan. Note
 
 After compilation we can also inspect the dependency graph visually by calling `BuildGraph`:
 
-![dependency graph](../../assets/images/data-builder.svg)
+![dependency graph](/assets/images/data-builder.svg)
 
 ### Running the execution plan and retrieving the results
 

howto/errors.md

@@ -184,7 +184,7 @@ name := notifier.GetTraceHeaderName()
 
 ## Examples
 
-### Sending errors to provides
+### Sending errors to providers
 
 The ColdBrew [notifier package] can be used to send errors to different providers like [Sentry], [Airbrake], [Rollbar] etc.