Write responds with a JSON error body and the given HTTP status. The caller should return immediately after (handlers do not abort the Gin chain).

EXPECT returns an object that allows the caller to indicate expected use.

NewBookHandler wires persistence and cache into book HTTP handlers.

NewMockCache creates a new mock instance.

NewMockBookPersistence creates a new mock instance.

NewGormBookStore returns a BookPersistence backed by db.

withBookActor injects the authenticated user id as JWTAuth would (for handler tests).

NewBookService constructs a BookService.

BooksListDataCacheKey is the Redis key for a cached books list page (tests and docs).

GenerateToken issues an HS256 JWT with username and user_id claims. userID must be non-zero (database primary key of the authenticated user).

APIKeyAuth returns Gin middleware that validates the X-API-Key header against the configured secret using a constant-time comparison.

IsBookNotFound reports whether err is a missing-book lookup from GORM.

EXPECT returns an object that allows the caller to indicate expected use.

SetJWTSigningKey configures the symmetric key used to sign and verify JWTs. It must be called once during application startup with a secret of at leas

JWTAuth returns Gin middleware that requires a valid Bearer JWT signed with HMAC-SHA256 using the application's JWT secret. Other algorithms are rejec

JWTSigningKey returns a copy of the configured JWT HMAC secret, or nil if SetJWTSigningKey has not completed successfully.

NewUserHandler wires persistence into user HTTP handlers.

Abort responds with a JSON error body, sets the HTTP status, and aborts the Gin chain so no later handlers run. Use in middleware.

NewGormUserStore returns a UserPersistence backed by db.

ListBooks returns books for offset/limit using Redis list cache and singleflight on miss.

NewUserService constructs a UserService.

OK writes HTTP 200 with the standard JSON envelope {"data": <payload>}.

IsUserNotFound reports whether err is a missing-user lookup from GORM.

Register creates a new user account.

JWTKeyFunc returns a jwt.Keyfunc for ParseWithClaims that only accepts tokens signed with HMAC-SHA256 using key. Any other signing method (including "

Login validates credentials and returns a JWT token string.

NewMockUserPersistence creates a new mock instance.

SetAPISecretKey configures the expected raw value for the X-API-Key header. It must be called during application startup with a non-empty secret of at

GetRequestID returns the request id stored in gin context.

1 MiB MaxRequestBody returns middleware that caps how many bytes handlers may read from the request body for POST, PUT, and PATCH. Larger bodies yield

bumpListCacheGeneration invalidates cached list pages by incrementing a global generation counter (BooksListCacheGenKey). Cached keys embed the genera

configureTrustedProxies sets which upstreams may influence ClientIP via X-Forwarded-For and related headers. If GIN_TRUSTED_PROXIES is unset or blank,

contextUserID returns the authenticated users.id set by middleware.JWTAuth.

Created writes HTTP 201 with the standard JSON envelope {"data": <payload>}.

ReplaceBook replaces title and author when actorID owns the book (PUT semantics).

RequestContextTimeout returns middleware that attaches a derived context.WithTimeout to c.Request, so handlers and services using c.Request.Context()

RequestID ensures every request has a stable request id.

testBookWriteMiddlewareStack mirrors NewRouter book mutation middleware so JWT requirements stay aligned with production routes.

ClearJWTSigningKeyForTesting drops the configured signing key. It is only intended for tests that cover misconfiguration; callers must restore a valid

CreateBook persists a new book owned by ownerID and bumps the list cache generation.

DeleteBook removes a book when actorID owns it, then bumps list cache generation.

Get mocks base method.

GetBook returns a book by id or gorm.ErrRecordNotFound-compatible error from the store.

GetRequestIDFromContext reads the request id from context.

NewDatabase opens PostgreSQL using POSTGRES_* environment variables, retries on failure, runs AutoMigrate for application models, and configures the u

PatchBook applies a partial update for any non-nil title/author pointers (PATCH semantics).

PatchFields updates only non-nil pointer fields (partial update).

configureConnPool applies *sql.DB pool settings from POSTGRES_* env vars (with sane defaults). max idle connections is capped at max open.

envTruthy reports whether the named environment variable is set to a conventional affirmative value (1, true, yes, on), case-insensitive.

ClearAPISecretKeyForTesting removes the configured API secret. Intended only for tests; callers must restore a valid key (for example via t.Cleanup).

EXPECT returns an object that allows the caller to indicate expected use.

NewRedisClient builds a go-redis client from environment variables. See redisOptionsFromEnv for supported keys and defaults.

NewRouter builds the Gin engine with middleware, Swagger, and API routes.