Docs overhaul: cleanup, fixes, and improvements

.github/workflows/playwright.yml

@@ -0,0 +1,51 @@
+name: Playwright Tests
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.1"
+          bundler-cache: true
+
+      - name: Build Jekyll site
+        run: bundle exec jekyll build
+        env:
+          JEKYLL_ENV: production
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright Chromium
+        run: npx playwright install chromium
+
+      - name: Run Playwright tests
+        run: npx playwright test
+        env:
+          CI: true
+
+      - name: Upload test report
+        uses: actions/upload-artifact@v4
+        if: ${{ !cancelled() }}
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 14

.gitignore

@@ -1 +1,4 @@
 _site
+node_modules
+test-results
+playwright-report

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.

Gemfile

@@ -7,3 +7,10 @@ gem "jekyll-github-metadata", ">= 2.15"
 gem "webrick", "~> 1.7"
 gem 'jekyll-target-blank'
 gem "jekyll-sitemap"
+
+# Required for Ruby 4.0+ (removed from default gems)
+gem "logger"
+gem "csv"
+gem "ostruct"
+gem "base64"
+gem "bigdecimal"

Gemfile.lock

@@ -3,8 +3,11 @@ GEM
   specs:
     addressable (2.8.4)
       public_suffix (>= 2.0.2, < 6.0)
+    base64 (0.3.0)
+    bigdecimal (4.0.1)
     colorator (1.1.0)
     concurrent-ruby (1.2.2)
+    csv (3.3.5)
     em-websocket (0.5.3)
       eventmachine (>= 0.12.9)
       http_parser.rb (~> 0)
@@ -15,9 +18,7 @@ GEM
     faraday-net_http (3.0.2)
     ffi (1.15.5)
     forwardable-extended (2.6.0)
-    google-protobuf (3.22.3-arm64-darwin)
-    google-protobuf (3.22.3-x86_64-darwin)
-    google-protobuf (3.22.3-x86_64-linux)
+    google-protobuf (3.22.3)
     http_parser.rb (0.8.0)
     i18n (1.12.0)
       concurrent-ruby (~> 1.0)
@@ -65,16 +66,16 @@ GEM
     listen (3.8.0)
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
+    logger (1.7.0)
     mercenary (0.4.0)
-    nokogiri (1.13.10-arm64-darwin)
-      racc (~> 1.4)
-    nokogiri (1.13.10-x86_64-darwin)
-      racc (~> 1.4)
-    nokogiri (1.13.10-x86_64-linux)
+    mini_portile2 (2.8.9)
+    nokogiri (1.13.10)
+      mini_portile2 (~> 2.8.0)
       racc (~> 1.4)
     octokit (4.25.1)
       faraday (>= 1, < 3)
       sawyer (~> 0.9)
+    ostruct (0.6.3)
     pathutil (0.16.2)
       forwardable-extended (~> 2.6)
     public_suffix (5.0.1)
@@ -87,9 +88,12 @@ GEM
     rouge (3.30.0)
     ruby2_keywords (0.0.5)
     safe_yaml (1.0.5)
-    sass-embedded (1.58.3)
+    sass-embedded (1.58.3-arm64-darwin)
+      google-protobuf (~> 3.21)
+    sass-embedded (1.58.3-x86_64-darwin)
+      google-protobuf (~> 3.21)
+    sass-embedded (1.58.3-x86_64-linux-gnu)
       google-protobuf (~> 3.21)
-      rake (>= 10.0.0)
     sawyer (0.9.2)
       addressable (>= 2.3.5)
       faraday (>= 0.17.3, < 3)
@@ -100,16 +104,22 @@ GEM
 
 PLATFORMS
   arm64-darwin-22
+  arm64-darwin-25
   x86_64-darwin-21
   x86_64-linux
 
 DEPENDENCIES
+  base64
+  bigdecimal
+  csv
   jekyll (~> 4.3)
   jekyll-default-layout
   jekyll-github-metadata (>= 2.15)
   jekyll-sitemap
   jekyll-target-blank
   just-the-docs (= 0.5.0)
+  logger
+  ostruct
   webrick (~> 1.7)
 
 BUNDLED WITH

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/