From 455ed666316085615856dc17d1a8d1180b3ed598 Mon Sep 17 00:00:00 2001
From: David Allen <david@datariot.io>
Date: Tue, 7 Jul 2026 09:18:13 -0600
Subject: [PATCH] docs: correct stale postgresql Initialize comment, enrich jwt
 godoc
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Late-arriving godoc pass on the bundles:
- postgresql: Initialize no longer claims it 'performs migrations if configured' — the bundle does not run migrations (a deployment concern per the package doc); comment now describes validate -> open pool -> apply limits -> ping
- jwt: enrich ServiceID/ServiceName (explain context-population mechanism, empty-string-on-no-claims), document TokenValidator.ValidateToken interface method and deepen the TokenValidator type doc

Doc comments only; build/vet/lint/tests clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 bundles/jwt/bundle.go        | 20 +++++++++++++++++---
 bundles/postgresql/bundle.go |  5 ++++-
 2 files changed, 21 insertions(+), 4 deletions(-)

diff --git a/bundles/jwt/bundle.go b/bundles/jwt/bundle.go
index e0fd6cf..0cbf11e 100644
--- a/bundles/jwt/bundle.go
+++ b/bundles/jwt/bundle.go
@@ -205,7 +205,10 @@ func (b *Bundle) Name() string {
 	return "jwt-auth"
 }
 
-// Initialize sets up JWT authentication.
+// Initialize validates the JWT configuration during application startup. The
+// bundle holds no external resources, so no connections are opened here; the
+// interceptors and middleware it exposes must be wired into the framework
+// explicitly by the caller.
 func (b *Bundle) Initialize(app *framework.App) error {
 	if err := b.config.Validate(); err != nil {
 		return forgeerrors.ErrInvalidConfiguration.WithMessage("JWT configuration validation failed").WithCause(err)
@@ -571,7 +574,10 @@ func HasPermission(ctx context.Context, permission string) bool {
 	return false
 }
 
-// ServiceID returns the authenticated service ID from context.
+// ServiceID extracts the caller's service ID from a context that the JWT
+// server interceptor (or HTTP middleware) previously populated with validated
+// claims. It returns the empty string when the context carries no claims, so
+// callers can use it for logging or coarse authorization without a nil check.
 func ServiceID(ctx context.Context) string {
 	claims := ClaimsFromContext(ctx)
 	if claims == nil {
@@ -580,7 +586,10 @@ func ServiceID(ctx context.Context) string {
 	return claims.ServiceID
 }
 
-// ServiceName returns the authenticated service name from context.
+// ServiceName extracts the caller's service name from a context that the JWT
+// server interceptor (or HTTP middleware) previously populated with validated
+// claims. It returns the empty string when the context carries no claims, so
+// callers can use it for logging or coarse authorization without a nil check.
 func ServiceName(ctx context.Context) string {
 	claims := ClaimsFromContext(ctx)
 	if claims == nil {
@@ -593,7 +602,12 @@ func ServiceName(ctx context.Context) string {
 type claimsContextKeyType struct{}
 
 // TokenValidator provides an interface for custom token validation logic.
+// Implementations can enforce application-specific rules (for example
+// revocation checks or per-tenant policy) on top of the bundle's standard
+// signature, expiry, audience, and issuer validation.
 type TokenValidator interface {
+	// ValidateToken applies custom validation to already-parsed claims and
+	// returns a non-nil error to reject the token.
 	ValidateToken(ctx context.Context, claims *ServiceClaims) error
 }
 
diff --git a/bundles/postgresql/bundle.go b/bundles/postgresql/bundle.go
index 45677d0..f1c050d 100644
--- a/bundles/postgresql/bundle.go
+++ b/bundles/postgresql/bundle.go
@@ -116,7 +116,10 @@ func (b *Bundle) Name() string {
 	return "postgresql"
 }
 
-// Initialize sets up the PostgreSQL connection and performs migrations if configured.
+// Initialize validates the configuration, opens the PostgreSQL connection
+// pool, applies the configured pool limits, and verifies connectivity with a
+// ping before the bundle is considered ready. It does not run migrations,
+// which are treated as a deployment concern (see the package documentation).
 func (b *Bundle) Initialize(app *framework.App) error {
 	if b.config.DatabaseURL == "" {
 		return forgeerrors.ErrInvalidConfiguration.WithMessage("database_url is required for PostgreSQL bundle")