diff --git a/.github/workflows/jekyll.yml b/.github/workflows/jekyll.yml index 389ecb6..1caa509 100644 --- a/.github/workflows/jekyll.yml +++ b/.github/workflows/jekyll.yml @@ -36,7 +36,7 @@ jobs: - name: Setup Ruby uses: ruby/setup-ruby@c515ec17f69368147deb311832da000dd229d338 # v1.297.0 with: - ruby-version: '3.1' # Not needed with a .ruby-version file + ruby-version: '3.2' # public_suffix 7.x requires Ruby >= 3.2 bundler-cache: true # runs 'bundle install' and caches installed gems automatically cache-version: 0 # Increment this number if you need to re-download cached gems - name: Setup Pages diff --git a/.github/workflows/playwright.yml b/.github/workflows/playwright.yml index e5809f3..6a8bef8 100644 --- a/.github/workflows/playwright.yml +++ b/.github/workflows/playwright.yml @@ -20,7 +20,7 @@ jobs: - name: Setup Ruby uses: ruby/setup-ruby@c515ec17f69368147deb311832da000dd229d338 # v1.297.0 with: - ruby-version: "3.1" + ruby-version: "3.2" bundler-cache: true - name: Build Jekyll site diff --git a/FAQ.md b/FAQ.md index c882ee3..08486b7 100644 --- a/FAQ.md +++ b/FAQ.md @@ -1,7 +1,7 @@ --- layout: default title: "FAQ" -nav_order: 8 +nav_order: 7 description: "Frequently asked questions about ColdBrew: gRPC framework configuration, interceptors, tracing, and troubleshooting" permalink: /faq --- diff --git a/Gemfile b/Gemfile index 7166b60..172c708 100644 --- a/Gemfile +++ b/Gemfile @@ -1,7 +1,7 @@ source 'https://rubygems.org' gem "jekyll", "~> 4.3" -gem "just-the-docs", "0.5.0" +gem "just-the-docs", "0.10.1" gem "jekyll-default-layout" gem "jekyll-github-metadata", ">= 2.15" gem "webrick", "~> 1.7" diff --git a/Gemfile.lock b/Gemfile.lock index c65332a..2d52917 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -1,12 +1,12 @@ GEM remote: https://rubygems.org/ specs: - addressable (2.8.4) - public_suffix (>= 2.0.2, < 6.0) + addressable (2.9.0) + public_suffix (>= 2.0.2, < 8.0) base64 (0.3.0) bigdecimal (4.0.1) colorator (1.1.0) - concurrent-ruby (1.2.2) + concurrent-ruby (1.3.6) csv (3.3.5) em-websocket (0.5.3) eventmachine (>= 0.12.9) @@ -16,23 +16,36 @@ GEM faraday-net_http (>= 2.0, < 3.1) ruby2_keywords (>= 0.0.4) faraday-net_http (3.0.2) - ffi (1.15.5) + ffi (1.17.4-arm64-darwin) + ffi (1.17.4-x86_64-darwin) + ffi (1.17.4-x86_64-linux-gnu) forwardable-extended (2.6.0) - google-protobuf (3.22.3) - http_parser.rb (0.8.0) - i18n (1.12.0) + google-protobuf (4.34.1-arm64-darwin) + bigdecimal + rake (~> 13.3) + google-protobuf (4.34.1-x86_64-darwin) + bigdecimal + rake (~> 13.3) + google-protobuf (4.34.1-x86_64-linux-gnu) + bigdecimal + rake (~> 13.3) + http_parser.rb (0.8.1) + i18n (1.14.8) concurrent-ruby (~> 1.0) - jekyll (4.3.2) + jekyll (4.4.1) addressable (~> 2.4) + base64 (~> 0.2) colorator (~> 1.0) + csv (~> 3.0) em-websocket (~> 0.5) i18n (~> 1.0) jekyll-sass-converter (>= 2.0, < 4.0) jekyll-watch (~> 2.0) + json (~> 2.6) kramdown (~> 2.3, >= 2.3.1) kramdown-parser-gfm (~> 1.0) liquid (~> 4.0) - mercenary (>= 0.3.6, < 0.5) + mercenary (~> 0.3, >= 0.3.6) pathutil (~> 0.9) rouge (>= 3.0, < 5.0) safe_yaml (~> 1.0) @@ -43,8 +56,10 @@ GEM jekyll-github-metadata (2.16.0) jekyll (>= 3.4, < 5.0) octokit (>= 4, < 7, != 4.4.0) - jekyll-sass-converter (3.0.0) - sass-embedded (~> 1.54) + jekyll-include-cache (0.2.1) + jekyll (>= 3.7, < 5.0) + jekyll-sass-converter (3.1.0) + sass-embedded (~> 1.75) jekyll-seo-tag (2.8.0) jekyll (>= 3.8, < 5.0) jekyll-sitemap (1.4.0) @@ -54,16 +69,19 @@ GEM nokogiri (~> 1.10) jekyll-watch (2.2.1) listen (~> 3.0) - just-the-docs (0.5.0) + json (2.19.3) + just-the-docs (0.10.1) jekyll (>= 3.8.5) + jekyll-include-cache jekyll-seo-tag (>= 2.0) rake (>= 12.3.1) - kramdown (2.4.0) - rexml + kramdown (2.5.2) + rexml (>= 3.4.4) kramdown-parser-gfm (1.1.0) kramdown (~> 2.0) liquid (4.0.4) - listen (3.8.0) + listen (3.10.0) + logger rb-fsevent (~> 0.10, >= 0.10.3) rb-inotify (~> 0.9, >= 0.9.10) logger (1.7.0) @@ -78,29 +96,29 @@ GEM ostruct (0.6.3) pathutil (0.16.2) forwardable-extended (~> 2.6) - public_suffix (5.0.1) + public_suffix (7.0.5) racc (1.6.2) - rake (13.0.6) + rake (13.3.1) rb-fsevent (0.11.2) - rb-inotify (0.10.1) + rb-inotify (0.11.1) ffi (~> 1.0) - rexml (3.2.5) - rouge (3.30.0) + rexml (3.4.4) + rouge (4.7.0) ruby2_keywords (0.0.5) safe_yaml (1.0.5) - 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) + sass-embedded (1.99.0-arm64-darwin) + google-protobuf (~> 4.31) + sass-embedded (1.99.0-x86_64-darwin) + google-protobuf (~> 4.31) + sass-embedded (1.99.0-x86_64-linux-gnu) + google-protobuf (~> 4.31) sawyer (0.9.2) addressable (>= 2.3.5) faraday (>= 0.17.3, < 3) terminal-table (3.0.2) unicode-display_width (>= 1.1.1, < 3) - unicode-display_width (2.4.2) - webrick (1.8.1) + unicode-display_width (2.6.0) + webrick (1.9.2) PLATFORMS arm64-darwin-22 @@ -117,7 +135,7 @@ DEPENDENCIES jekyll-github-metadata (>= 2.15) jekyll-sitemap jekyll-target-blank - just-the-docs (= 0.5.0) + just-the-docs (= 0.10.1) logger ostruct webrick (~> 1.7) diff --git a/Index.md b/Index.md index 767097c..c1b253e 100644 --- a/Index.md +++ b/Index.md @@ -146,7 +146,9 @@ ColdBrew handles all of it. You write business logic, ColdBrew handles everythin | Nothing | Prometheus metrics at `/metrics` — per-method latency, error rate, QPS | | Nothing | Health/ready probes, graceful shutdown, [pprof] profiling | | Nothing | Interceptor chain: logging, tracing, metrics, panic recovery | +| Proto validation annotations | Request validation via [Protovalidate] — `InvalidArgument` on failure, covers gRPC and HTTP | | Nothing | [vtprotobuf] codec — up to ~4x faster proto marshal | +| Nothing | HTTP content negotiation — JSON, `application/proto`, `application/protobuf` out of the box | | Nothing | HTTP [gzip/zstd][zstd] compression, container-aware [GOMAXPROCS][automaxprocs] | New services inherit all of this automatically via the [cookiecutter template](/getting-started) — zero boilerplate to write, zero infrastructure to maintain. @@ -157,7 +159,7 @@ ColdBrew composes proven Go libraries — not replacements: | Category | Libraries | |----------|----------| -| **API** | [grpc] + [grpc-gateway] — gRPC server with automatic REST gateway and Swagger UI | +| **API** | [grpc] + [grpc-gateway] — gRPC server with automatic REST gateway and Swagger UI; [Protovalidate] — request validation | | **Observability** | [OpenTelemetry] + [Jaeger] — distributed tracing; [Prometheus] + [go-grpc-middleware] — metrics | | **Monitoring** | [New Relic] — APM; [Sentry] — error tracking and alerting | | **Performance** | [vtprotobuf] — fast serialization; [klauspost/compress][zstd] — gzip/zstd HTTP compression | diff --git a/Packages.md b/Packages.md index 1ed318a..13e2695 100644 --- a/Packages.md +++ b/Packages.md @@ -3,7 +3,7 @@ layout: default title: Packages description: "ColdBrew Go packages: core, interceptors, errors, log, tracing, options, grpcpool, and data-builder API reference" permalink: /packages -nav_order: 9 +nav_order: 8 --- # Packages {: .no_toc } diff --git a/_config.yml b/_config.yml index 35d29dc..b4930b0 100644 --- a/_config.yml +++ b/_config.yml @@ -1,8 +1,8 @@ title: ColdBrew description: "ColdBrew is a Go microservice framework for building production-grade gRPC services with built-in observability, resilience, and HTTP gateway support." -baseurl: "/" # the subpath of your site, e.g. /blog +baseurl: "" # the subpath of your site, e.g. /blog url: "https://docs.coldbrew.cloud" -repository: go-coldbrew/ +repository: go-coldbrew/docs.coldbrew.cloud logo: "/assets/images/coldbrew.png" favicon_ico: "/assets/images/coldbrew.ico" @@ -50,9 +50,6 @@ gh_edit_branch: "main" # the branch that your docs is served from # gh_edit_source: docs # the source that your files originate from gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately -ga_tracking: "G-ZRR08Y74FZ" - -#color_scheme: dark plugins: - jekyll-default-layout - jekyll-seo-tag diff --git a/_includes/head_custom.html b/_includes/head_custom.html new file mode 100644 index 0000000..328ac40 --- /dev/null +++ b/_includes/head_custom.html @@ -0,0 +1,10 @@ +{% if jekyll.environment == 'production' %} + + + +{% endif %} diff --git a/_sass/custom/setup.scss b/_sass/custom/setup.scss new file mode 100644 index 0000000..4159237 --- /dev/null +++ b/_sass/custom/setup.scss @@ -0,0 +1 @@ +$content-width: 66rem; diff --git a/architecture.md b/architecture.md index 87e12c6..d2e9488 100644 --- a/architecture.md +++ b/architecture.md @@ -1,7 +1,7 @@ --- layout: default title: "Architecture" -nav_order: 5 +nav_order: 3 description: "ColdBrew architecture: request lifecycle, interceptor chain, and package dependencies" permalink: /architecture --- diff --git a/config-reference.md b/config-reference.md index b7074b2..81f4da5 100644 --- a/config-reference.md +++ b/config-reference.md @@ -1,7 +1,7 @@ --- layout: default title: "Configuration Reference" -nav_order: 5 +nav_order: 4 description: "Complete environment variable reference for ColdBrew Go microservice framework configuration" permalink: /config-reference --- diff --git a/howto/APIs.md b/howto/APIs.md index 40a3706..2e55d49 100644 --- a/howto/APIs.md +++ b/howto/APIs.md @@ -2,6 +2,7 @@ layout: default title: "Building and Configuring APIs" parent: "How To" +nav_order: 1 description: "Build gRPC and REST APIs with ColdBrew using protobuf definitions and grpc-gateway HTTP annotations" --- ## Table of contents diff --git a/howto/Debugging.md b/howto/Debugging.md index 43695ff..5f121eb 100644 --- a/howto/Debugging.md +++ b/howto/Debugging.md @@ -2,6 +2,7 @@ layout: default title: "Debugging" parent: "How To" +nav_order: 8 description: "Debugging ColdBrew services with pprof and log overrides" --- ## Table of contents diff --git a/howto/Log.md b/howto/Log.md index 0e0af1c..ea7f51f 100644 --- a/howto/Log.md +++ b/howto/Log.md @@ -2,6 +2,7 @@ layout: default title: "Log" parent: "How To" +nav_order: 3 description: "Context-aware logging and trace ID propagation in ColdBrew" --- ## Table of contents diff --git a/howto/Metrics.md b/howto/Metrics.md index 7e79bea..d30721e 100644 --- a/howto/Metrics.md +++ b/howto/Metrics.md @@ -2,7 +2,8 @@ layout: default title: "Metrics" parent: "How To" -description: "Prometheus metrics and custom metrics in ColdBrew" +nav_order: 6 +description: "Prometheus metrics and custom metrics in ColdBrew: default runtime metrics, custom counters and histograms, and Hystrix circuit breaker monitoring" --- ## Table of contents {: .no_toc .text-delta } diff --git a/howto/Tracing.md b/howto/Tracing.md index 714ab78..43faccc 100644 --- a/howto/Tracing.md +++ b/howto/Tracing.md @@ -2,6 +2,7 @@ layout: default title: "Tracing" parent: "How To" +nav_order: 5 description: "Set up distributed tracing in ColdBrew with OpenTelemetry and New Relic for gRPC services" --- ## Table of contents diff --git a/howto/data-builder.md b/howto/data-builder.md index 9ecac5b..97519a8 100644 --- a/howto/data-builder.md +++ b/howto/data-builder.md @@ -2,6 +2,7 @@ layout: default title: "Data Builder" parent: "How To" +nav_order: 11 description: "How to use go-coldbrew/data-builder package to orchestrate data-processing logic in Go." --- ## Table of contents diff --git a/howto/errors.md b/howto/errors.md index b0e46f0..68a0bb8 100644 --- a/howto/errors.md +++ b/howto/errors.md @@ -2,6 +2,7 @@ layout: default title: "Errors" parent: "How To" +nav_order: 4 description: "How to use go-coldbrew/errors package to handle errors in Go." --- ## Table of contents diff --git a/howto/gRPC.md b/howto/gRPC.md index 1a8afbe..9a92504 100644 --- a/howto/gRPC.md +++ b/howto/gRPC.md @@ -2,7 +2,8 @@ layout: default title: "gRPC" parent: "How To" -description: "How to use gRPC with ColdBrew" +nav_order: 2 +description: "How to use gRPC with ColdBrew: connection pooling, client setup with grpcpool, and building gRPC-first microservices in Go" --- ## Table of contents {: .no_toc .text-delta } diff --git a/howto/index.md b/howto/index.md index 2d675ea..5f69b60 100644 --- a/howto/index.md +++ b/howto/index.md @@ -1,7 +1,7 @@ --- layout: default title: How To -nav_order: 6 +nav_order: 5 description: "Step-by-step guides for logging, tracing, metrics, error handling, APIs, and debugging in ColdBrew Go services" permalink: /howto has_children: true diff --git a/howto/interceptors.md b/howto/interceptors.md index 11d7116..4642ee6 100644 --- a/howto/interceptors.md +++ b/howto/interceptors.md @@ -2,6 +2,7 @@ layout: default title: "Interceptors" parent: "How To" +nav_order: 7 description: "Configuring gRPC interceptors in ColdBrew" --- ## Table of contents diff --git a/howto/private-modules.md b/howto/private-modules.md index 67f1505..08b3e9b 100644 --- a/howto/private-modules.md +++ b/howto/private-modules.md @@ -2,6 +2,7 @@ layout: default title: "Private Modules" parent: "How To" +nav_order: 16 description: "Configure Go private modules for GitHub and GitLab private repositories in ColdBrew services" --- ## Table of contents diff --git a/howto/production.md b/howto/production.md index d6ea841..4ed9fc5 100644 --- a/howto/production.md +++ b/howto/production.md @@ -2,6 +2,7 @@ layout: default title: "Production Deployment" parent: "How To" +nav_order: 13 description: "Deploy ColdBrew Go services to production with Kubernetes manifests, health probes, Prometheus, distributed tracing, and graceful shutdown" --- ## Table of contents diff --git a/howto/signals.md b/howto/signals.md index ad5f512..fa17ab6 100644 --- a/howto/signals.md +++ b/howto/signals.md @@ -2,6 +2,7 @@ layout: default title: "Signal Handling and Graceful Shutdown" parent: "How To" +nav_order: 9 description: "How POSIX signal handling works in ColdBrew" --- ## Table of contents diff --git a/howto/swagger.md b/howto/swagger.md index aa535bd..c5fb71a 100644 --- a/howto/swagger.md +++ b/howto/swagger.md @@ -2,6 +2,7 @@ layout: default title: "Swagger / Open API Support" parent: "How To" +nav_order: 10 description: "How ColdBrew supports Swagger / Open API" --- ## Table of contents diff --git a/howto/testing.md b/howto/testing.md index 9929f7c..c9a3f11 100644 --- a/howto/testing.md +++ b/howto/testing.md @@ -2,6 +2,7 @@ layout: default title: "Testing" parent: "How To" +nav_order: 14 description: "Unit tests, mocks, benchmarks, and coverage reports in ColdBrew services" --- ## Table of contents diff --git a/howto/vtproto.md b/howto/vtproto.md index 11a6b19..2466308 100644 --- a/howto/vtproto.md +++ b/howto/vtproto.md @@ -2,6 +2,7 @@ layout: default title: "VTProtobuf (Fast Serialization)" parent: "How To" +nav_order: 12 description: "How ColdBrew uses vtprotobuf for faster gRPC serialization with automatic fallback to standard protobuf" --- ## Table of contents diff --git a/howto/workers.md b/howto/workers.md index 6452615..db829e7 100644 --- a/howto/workers.md +++ b/howto/workers.md @@ -2,6 +2,7 @@ layout: default title: "Workers" parent: "How To" +nav_order: 15 description: "How to use go-coldbrew/workers to manage background goroutines with panic recovery, restart, and structured shutdown." --- ## Table of contents diff --git a/integrations.md b/integrations.md index 102b216..31fd2b3 100644 --- a/integrations.md +++ b/integrations.md @@ -2,8 +2,8 @@ layout: default title: Integrations permalink: /integrations -description: ColdBrew integrations with other services and tools -nav_order: 7 +description: "ColdBrew integrations with Prometheus, New Relic, Sentry, OpenTelemetry, Buf, Jaeger, and vtprotobuf for observability and code generation" +nav_order: 6 --- # Integrations {: .no_toc } diff --git a/robots.txt b/robots.txt new file mode 100644 index 0000000..45a1269 --- /dev/null +++ b/robots.txt @@ -0,0 +1,8 @@ +--- +layout: null +sitemap: false +--- +User-agent: * +Allow: / + +Sitemap: {{ site.url }}/sitemap.xml diff --git a/tests/content.spec.ts b/tests/content.spec.ts index cbd3f96..851cb00 100644 --- a/tests/content.spec.ts +++ b/tests/content.spec.ts @@ -32,13 +32,13 @@ test.describe("Tables", () => { const tables = page.locator("table"); expect(await tables.count()).toBeGreaterThanOrEqual(1); // Check that the status code table exists - const pageText = await page.locator("main, .main-content").textContent(); + const pageText = await page.locator("main, .main-content").first().textContent(); expect(pageText).toContain("gRPC status code"); }); test("integrations page renders content", async ({ page }) => { await page.goto("/integrations/"); - const pageText = await page.locator("main, .main-content").textContent(); + const pageText = await page.locator("main, .main-content").first().textContent(); expect(pageText).toContain("Prometheus"); expect(pageText).toContain("New Relic"); }); @@ -84,7 +84,7 @@ test.describe("Callouts", () => { test("metrics page has warning about hystrix", async ({ page }) => { await page.goto("/howto/Metrics/"); - const pageText = await page.locator("main, .main-content").textContent(); + const pageText = await page.locator("main, .main-content").first().textContent(); expect(pageText).toContain("unmaintained"); }); });