Merge branch 'tmdbconf'

Reviewed-on: #3

RULES.md

@@ -12,7 +12,7 @@ The README for each module should be laid out as follows:
 - Feature list (DO NOT USE EMOTICONS)
 - Installation (go get)
 - Quick Start (brief example of setting up and using)
-- Documentation links to the wiki
+- Documentation links to the wiki (path is `../golib/wiki/<package>.md`)
 - Additional information (e.g. supported databases if package has database features)
 - License
 - Contributing

hlog/README.md

@@ -55,7 +55,7 @@ func main() {
 
 ## Documentation
 
-For detailed documentation, see the [HLog Wiki](https://git.haelnorr.com/h/golib-wiki/HLog).
+For detailed documentation, see the [HLog Wiki](https://git.haelnorr.com/h/golib/wiki/HLog.md).
 
 Additional API documentation is available at [GoDoc](https://pkg.go.dev/git.haelnorr.com/h/golib/hlog).
 

hws/README.md

@@ -1,21 +1,19 @@
-# HWS (H Web Server)
+# HWS (H Web Server) - v0.2.2
 
-[![Go Reference](https://pkg.go.dev/badge/git.haelnorr.com/h/golib/hws.svg)](https://pkg.go.dev/git.haelnorr.com/h/golib/hws)
+A lightweight, opinionated HTTP web server framework for Go built on top of the standard library's net/http.
-
-A lightweight, opinionated HTTP web server framework for Go built on top of the standard library's `net/http`.
 
 ## Features
 
-- 🚀 Built on Go 1.22+ routing patterns with method and path matching
+- Built on Go 1.22+ routing patterns with method and path matching
-- 🎯 Structured error handling with customizable error pages
+- Structured error handling with customizable error pages
-- 📝 Integrated logging with zerolog via hlog
+- Integrated logging with zerolog via hlog
-- 🔧 Middleware support with predictable execution order
+- Middleware support with predictable execution order
-- 🗜️ GZIP compression support
+- GZIP compression support
-- 🔒 Safe static file serving (prevents directory listing)
+- Safe static file serving (prevents directory listing)
-- ⚙️ Environment variable configuration
+- Environment variable configuration with ConfigFromEnv
-- ⏱️ Request timing and logging middleware
+- Request timing and logging middleware
-- 💚 Graceful shutdown support
+- Graceful shutdown support
-- 🏥 Built-in health check endpoint
+- Built-in health check endpoint
 
 ## Installation
 
@@ -30,8 +28,8 @@ package main
 
 import (
     "context"
-    "git.haelnorr.com/h/golib/hws"
     "net/http"
+    "git.haelnorr.com/h/golib/hws"
 )
 
 func main() {
@@ -79,34 +77,13 @@ func getUserHandler(w http.ResponseWriter, r *http.Request) {
 
 ## Documentation
 
-Comprehensive documentation is available in the [Wiki](https://git.haelnorr.com/h/golib/wiki/hws).
+For detailed documentation, see the [HWS Wiki](https://git.haelnorr.com/h/golib/wiki/HWS.md).
 
-### Key Topics
+Additional API documentation is available at [GoDoc](https://pkg.go.dev/git.haelnorr.com/h/golib/hws).
-
-- [Configuration](https://git.haelnorr.com/h/golib/wiki/hws#configuration)
-- [Routing](https://git.haelnorr.com/h/golib/wiki/hws#routing)
-- [Middleware](https://git.haelnorr.com/h/golib/wiki/hws#middleware)
-- [Error Handling](https://git.haelnorr.com/h/golib/wiki/hws#error-handling)
-- [Logging](https://git.haelnorr.com/h/golib/wiki/hws#logging)
-- [Static Files](https://git.haelnorr.com/h/golib/wiki/hws#static-files)
-- [Graceful Shutdown](https://git.haelnorr.com/h/golib/wiki/hws#graceful-shutdown)
-- [Complete Examples](https://git.haelnorr.com/h/golib/wiki/hws#complete-production-example)
-
-## Environment Variables
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `HWS_HOST` | Host to listen on | `127.0.0.1` |
-| `HWS_PORT` | Port to listen on | `3000` |
-| `HWS_TRUSTED_HOST` | Trusted hostname/domain | Same as Host |
-| `HWS_GZIP` | Enable GZIP compression | `false` |
-| `HWS_READ_HEADER_TIMEOUT` | Header read timeout (seconds) | `2` |
-| `HWS_WRITE_TIMEOUT` | Write timeout (seconds) | `10` |
-| `HWS_IDLE_TIMEOUT` | Idle connection timeout (seconds) | `120` |
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License - see the LICENSE file for details.
 
 ## Contributing
 
@@ -114,6 +91,6 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 
 ## Related Projects
 
-- [HWSAuth](https://git.haelnorr.com/h/golib/hwsauth) - JWT authentication middleware for HWS
+- [hwsauth](https://git.haelnorr.com/h/golib/hwsauth) - JWT authentication middleware for HWS
 - [hlog](https://git.haelnorr.com/h/golib/hlog) - Structured logging with zerolog
 - [jwt](https://git.haelnorr.com/h/golib/jwt) - JWT token generation and validation

hws/doc.go

@@ -0,0 +1,144 @@
+// Package hws provides a lightweight HTTP web server framework built on top of Go's standard library.
+//
+// HWS (H Web Server) is an opinionated framework that leverages Go 1.22+ routing patterns
+// with built-in middleware, structured error handling, and production-ready defaults. It
+// integrates seamlessly with other golib packages like hlog for logging and hwsauth for
+// authentication.
+//
+// # Basic Usage
+//
+// Create a server with environment-based configuration:
+//
+//	cfg, err := hws.ConfigFromEnv()
+//	if err != nil {
+//		log.Fatal(err)
+//	}
+//
+//	server, err := hws.NewServer(cfg)
+//	if err != nil {
+//		log.Fatal(err)
+//	}
+//
+//	routes := []hws.Route{
+//		{
+//			Path:    "/",
+//			Method:  hws.MethodGET,
+//			Handler: http.HandlerFunc(homeHandler),
+//		},
+//	}
+//
+//	server.AddRoutes(routes...)
+//	server.AddMiddleware()
+//
+//	ctx := context.Background()
+//	server.Start(ctx)
+//
+//	<-server.Ready()
+//
+// # Configuration
+//
+// HWS can be configured via environment variables using ConfigFromEnv:
+//
+//	HWS_HOST=127.0.0.1                # Host to listen on (default: 127.0.0.1)
+//	HWS_PORT=3000                     # Port to listen on (default: 3000)
+//	HWS_GZIP=false                    # Enable GZIP compression (default: false)
+//	HWS_READ_HEADER_TIMEOUT=2         # Header read timeout in seconds (default: 2)
+//	HWS_WRITE_TIMEOUT=10              # Write timeout in seconds (default: 10)
+//	HWS_IDLE_TIMEOUT=120              # Idle connection timeout in seconds (default: 120)
+//
+// Or programmatically:
+//
+//	cfg := &hws.Config{
+//		Host:              "0.0.0.0",
+//		Port:              8080,
+//		GZIP:              true,
+//		ReadHeaderTimeout: 5 * time.Second,
+//		WriteTimeout:      15 * time.Second,
+//		IdleTimeout:       120 * time.Second,
+//	}
+//
+// # Routing
+//
+// HWS uses Go 1.22+ routing patterns with method-specific handlers:
+//
+//	routes := []hws.Route{
+//		{
+//			Path:    "/users/{id}",
+//			Method:  hws.MethodGET,
+//			Handler: http.HandlerFunc(getUser),
+//		},
+//		{
+//			Path:    "/users/{id}",
+//			Method:  hws.MethodPUT,
+//			Handler: http.HandlerFunc(updateUser),
+//		},
+//	}
+//
+// Path parameters can be accessed using r.PathValue():
+//
+//	func getUser(w http.ResponseWriter, r *http.Request) {
+//		id := r.PathValue("id")
+//		// ... handle request
+//	}
+//
+// # Middleware
+//
+// HWS supports middleware with predictable execution order. Built-in middleware includes
+// request logging, timing, and GZIP compression:
+//
+//	server.AddMiddleware()
+//
+// Custom middleware can be added using standard http.Handler wrapping:
+//
+//	server.AddMiddleware(customMiddleware)
+//
+// # Error Handling
+//
+// HWS provides structured error handling with customizable error pages:
+//
+//	errorPageFunc := func(w http.ResponseWriter, r *http.Request, status int) {
+//		w.WriteHeader(status)
+//		fmt.Fprintf(w, "Error: %d", status)
+//	}
+//
+//	server.AddErrorPage(errorPageFunc)
+//
+// # Logging
+//
+// HWS integrates with hlog for structured logging:
+//
+//	logger, _ := hlog.NewLogger(loggerCfg, os.Stdout)
+//	server.AddLogger(logger)
+//
+// The server will automatically log requests, errors, and server lifecycle events.
+//
+// # Static Files
+//
+// HWS provides safe static file serving that prevents directory listing:
+//
+//	server.AddStaticFiles("/static", "./public")
+//
+// # Graceful Shutdown
+//
+// HWS supports graceful shutdown via context cancellation:
+//
+//	ctx, cancel := context.WithCancel(context.Background())
+//	defer cancel()
+//
+//	server.Start(ctx)
+//
+//	// Wait for shutdown signal
+//	sigChan := make(chan os.Signal, 1)
+//	signal.Notify(sigChan, os.Interrupt, syscall.SIGTERM)
+//	<-sigChan
+//
+//	// Cancel context to trigger graceful shutdown
+//	cancel()
+//
+// # Integration
+//
+// HWS integrates with:
+//   - git.haelnorr.com/h/golib/hlog: For structured logging with zerolog
+//   - git.haelnorr.com/h/golib/hwsauth: For JWT-based authentication
+//   - git.haelnorr.com/h/golib/jwt: For JWT token management
+package hws

hwsauth/README.md

@@ -1,19 +1,19 @@
-# HWSAuth
+# HWSAuth - v0.3.3
 
-[![Go Reference](https://pkg.go.dev/badge/git.haelnorr.com/h/golib/hwsauth.svg)](https://pkg.go.dev/git.haelnorr.com/h/golib/hwsauth)
+JWT-based authentication middleware for the HWS web framework.
-
-JWT-based authentication middleware for the [HWS](https://git.haelnorr.com/h/golib/hws) web framework.
 
 ## Features
 
-- 🔐 JWT-based authentication with access and refresh tokens
+- JWT-based authentication with access and refresh tokens
-- 🔄 Automatic token rotation and refresh
+- Automatic token rotation and refresh
-- 🎯 Generic over user model and transaction types
+- Generic over user model and transaction types
-- 💾 ORM-agnostic transaction handling (works with GORM, Bun, sqlx, etc.)
+- ORM-agnostic transaction handling (works with GORM, Bun, sqlx, database/sql)
-- ⚙️ Environment variable configuration
+- Environment variable configuration with ConfigFromEnv
-- 🛡️ Middleware for protecting routes
+- Middleware for protecting routes
-- 🔒 SSL cookie security support
+- SSL cookie security support
-- 📦 Type-safe with Go generics
+- Type-safe with Go generics
+- Path ignoring for public routes
+- Automatic re-authentication handling
 
 ## Installation
 
@@ -29,9 +29,10 @@ package main
 import (
     "context"
     "database/sql"
+    "net/http"
     "git.haelnorr.com/h/golib/hwsauth"
     "git.haelnorr.com/h/golib/hws"
-    "github.com/rs/zerolog"
+    "git.haelnorr.com/h/golib/hlog"
 )
 
 type User struct {
@@ -69,6 +70,15 @@ func main() {
     serverCfg, _ := hws.ConfigFromEnv()
     server, _ := hws.NewServer(serverCfg)
 
+    // Create logger
+    logger, _ := hlog.NewLogger(loggerCfg, os.Stdout)
+
+    // Create error page function
+    errorPageFunc := func(w http.ResponseWriter, r *http.Request, status int) {
+        w.WriteHeader(status)
+        fmt.Fprintf(w, "Error: %d", status)
+    }
+
     // Create authenticator
     auth, _ := hwsauth.NewAuthenticator[User, *sql.Tx](
         cfg,
@@ -93,7 +103,7 @@ func main() {
     // Add authentication middleware
     server.AddMiddleware(auth.Authenticate())
 
-    // Optionally ignore public paths
+    // Ignore public paths
     auth.IgnorePaths("/", "/login", "/register", "/static")
 
     // Start server
@@ -106,18 +116,9 @@ func main() {
 
 ## Documentation
 
-Comprehensive documentation is available in the [Wiki](https://git.haelnorr.com/h/golib/wiki/hwsauth).
+For detailed documentation, see the [HWSAuth Wiki](https://git.haelnorr.com/h/golib/wiki/HWSAuth.md).
 
-### Key Topics
+Additional API documentation is available at [GoDoc](https://pkg.go.dev/git.haelnorr.com/h/golib/hwsauth).
-
-- [Configuration](https://git.haelnorr.com/h/golib/wiki/hwsauth#configuration)
-- [User Model](https://git.haelnorr.com/h/golib/wiki/hwsauth#user-model)
-- [Authentication Flow](https://git.haelnorr.com/h/golib/wiki/hwsauth#authentication-flow)
-- [Login & Logout](https://git.haelnorr.com/h/golib/wiki/hwsauth#login-logout)
-- [Route Protection](https://git.haelnorr.com/h/golib/wiki/hwsauth#route-protection)
-- [Token Refresh](https://git.haelnorr.com/h/golib/wiki/hwsauth#token-refresh)
-- [Using with ORMs](https://git.haelnorr.com/h/golib/wiki/hwsauth#using-with-orms)
-- [Security Best Practices](https://git.haelnorr.com/h/golib/wiki/hwsauth#security-best-practices)
 
 ## Supported ORMs
 
@@ -128,7 +129,7 @@ Comprehensive documentation is available in the [Wiki](https://git.haelnorr.com/
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.
+This project is licensed under the MIT License - see the LICENSE file for details.
 
 ## Contributing
 
@@ -138,4 +139,4 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 
 - [hws](https://git.haelnorr.com/h/golib/hws) - The web server framework
 - [jwt](https://git.haelnorr.com/h/golib/jwt) - JWT token generation and validation
-
+- [hlog](https://git.haelnorr.com/h/golib/hlog) - Structured logging with zerolog

hwsauth/authenticator.go

@@ -1,10 +1,10 @@
 package hwsauth
 
 import (
+	"git.haelnorr.com/h/golib/hlog"
 	"git.haelnorr.com/h/golib/hws"
 	"git.haelnorr.com/h/golib/jwt"
 	"github.com/pkg/errors"
-	"github.com/rs/zerolog"
 )
 
 type Authenticator[T Model, TX DBTransaction] struct {
@@ -12,7 +12,7 @@ type Authenticator[T Model, TX DBTransaction] struct {
 	load           LoadFunc[T, TX]
 	beginTx        BeginTX
 	ignoredPaths   []string
-	logger         *zerolog.Logger
+	logger         *hlog.Logger
 	server         *hws.Server
 	errorPage      hws.ErrorPageFunc
 	SSL            bool   // Use SSL for JWT tokens. Default true
@@ -28,7 +28,7 @@ func NewAuthenticator[T Model, TX DBTransaction](
 	load LoadFunc[T, TX],
 	server *hws.Server,
 	beginTx BeginTX,
-	logger *zerolog.Logger,
+	logger *hlog.Logger,
 	errorPage hws.ErrorPageFunc,
 ) (*Authenticator[T, TX], error) {
 	if load == nil {

hwsauth/doc.go

@@ -179,18 +179,18 @@
 //
 // # Environment Variables
 //
-// The following environment variables are supported:
+// The following environment variables are supported when using ConfigFromEnv:
 //
-//   - HWSAUTH_SSL: Enable SSL mode (default: false)
+//   - HWSAUTH_SSL: Enable SSL secure cookies (default: false)
-//   - HWSAUTH_TRUSTED_HOST: Trusted host for SSL (required if SSL is true)
+//   - HWSAUTH_TRUSTED_HOST: Full server address for SSL (required if SSL is true)
-//   - HWSAUTH_SECRET_KEY: Secret key for signing tokens (required)
+//   - HWSAUTH_SECRET_KEY: Secret key for signing JWT tokens (required)
 //   - HWSAUTH_ACCESS_TOKEN_EXPIRY: Access token expiry in minutes (default: 5)
 //   - HWSAUTH_REFRESH_TOKEN_EXPIRY: Refresh token expiry in minutes (default: 1440)
 //   - HWSAUTH_TOKEN_FRESH_TIME: Token fresh time in minutes (default: 5)
-//   - HWSAUTH_LANDING_PAGE: Landing page for logged in users (default: "/profile")
+//   - HWSAUTH_LANDING_PAGE: Redirect destination for authenticated users (default: "/profile")
-//   - HWSAUTH_JWT_TABLE_NAME: Custom JWT table name (optional)
+//   - HWSAUTH_DATABASE_TYPE: Database type - postgres, mysql, sqlite, mariadb (default: "postgres")
-//   - HWSAUTH_DATABASE_TYPE: Database type (e.g., "postgres", "mysql")
+//   - HWSAUTH_DATABASE_VERSION: Database version string (default: "15")
-//   - HWSAUTH_DATABASE_VERSION: Database version (e.g., "15")
+//   - HWSAUTH_JWT_TABLE_NAME: Custom JWT blacklist table name (default: "jwtblacklist")
 //
 // # Security Considerations
 //

hwsauth/go.mod

@@ -8,11 +8,11 @@ require (
 	git.haelnorr.com/h/golib/hws v0.2.0
 	git.haelnorr.com/h/golib/jwt v0.10.0
 	github.com/pkg/errors v0.9.1
-	github.com/rs/zerolog v1.34.0
+	git.haelnorr.com/h/golib/hlog v0.9.1
 )
 
 require (
-	git.haelnorr.com/h/golib/hlog v0.9.1 // indirect
+	github.com/rs/zerolog v1.34.0 // indirect
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/golang-jwt/jwt v3.2.2+incompatible // indirect
 	github.com/google/uuid v1.6.0 // indirect

jwt/README.md

@@ -1,20 +1,19 @@
-# JWT Package
+# JWT - v0.10.1
-
-[![Go Reference](https://pkg.go.dev/badge/git.haelnorr.com/h/golib/jwt.svg)](https://pkg.go.dev/git.haelnorr.com/h/golib/jwt)
 
 JWT (JSON Web Token) generation and validation with database-backed token revocation support.
 
 ## Features
 
-- 🔐 Access and refresh token generation
+- Access and refresh token generation
-- ✅ Token validation with expiration checking
+- Token validation with expiration checking
-- 🚫 Token revocation via database blacklist
+- Token revocation via database blacklist
-- 🗄️ Multi-database support (PostgreSQL, MySQL, SQLite, MariaDB)
+- Multi-database support (PostgreSQL, MySQL, SQLite, MariaDB)
-- 🔧 Compatible with database/sql, GORM, and Bun
+- Compatible with database/sql, GORM, and Bun ORMs
-- 🤖 Automatic table creation and management
+- Automatic table creation and management
-- 🧹 Database-native automatic cleanup
+- Database-native automatic cleanup
-- 🔄 Token freshness tracking
+- Token freshness tracking for sensitive operations
-- 💾 "Remember me" functionality
+- "Remember me" functionality with session vs persistent tokens
+- Manual cleanup method for on-demand token cleanup
 
 ## Installation
 
@@ -41,7 +40,7 @@ func main() {
 
     // Create a transaction getter function
     txGetter := func(ctx context.Context) (jwt.DBTransaction, error) {
-        return db.Begin()
+        return db.BeginTx(ctx, nil)
     }
 
     // Create token generator
@@ -78,16 +77,9 @@ func main() {
 
 ## Documentation
 
-Comprehensive documentation is available in the [Wiki](https://git.haelnorr.com/h/golib/wiki/JWT).
+For detailed documentation, see the [JWT Wiki](https://git.haelnorr.com/h/golib/wiki/JWT.md).
 
-### Key Topics
+Additional API documentation is available at [GoDoc](https://pkg.go.dev/git.haelnorr.com/h/golib/jwt).
-
-- [Configuration](https://git.haelnorr.com/h/golib/wiki/JWT#configuration)
-- [Token Generation](https://git.haelnorr.com/h/golib/wiki/JWT#token-generation)
-- [Token Validation](https://git.haelnorr.com/h/golib/wiki/JWT#token-validation)
-- [Token Revocation](https://git.haelnorr.com/h/golib/wiki/JWT#token-revocation)
-- [Cleanup](https://git.haelnorr.com/h/golib/wiki/JWT#cleanup)
-- [Using with ORMs](https://git.haelnorr.com/h/golib/wiki/JWT#using-with-orms)
 
 ## Supported Databases
 
@@ -98,8 +90,13 @@ Comprehensive documentation is available in the [Wiki](https://git.haelnorr.com/
 
 ## License
 
-See LICENSE file in the repository root.
+This project is licensed under the MIT License - see the LICENSE file for details.
 
 ## Contributing
 
-Contributions are welcome! Please open an issue or submit a pull request.
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Related Projects
+
+- [hwsauth](https://git.haelnorr.com/h/golib/hwsauth) - JWT-based authentication middleware for HWS
+- [hws](https://git.haelnorr.com/h/golib/hws) - HTTP web server framework

tmdb/api.go

@@ -0,0 +1,26 @@
+package tmdb
+
+import (
+	"git.haelnorr.com/h/golib/env"
+	"github.com/pkg/errors"
+)
+
+type API struct {
+	*Config
+	token string // ENV TMDB_TOKEN: API token for TMDB (required)
+}
+
+func NewAPIConnection() (*API, error) {
+	token := env.String("TMDB_TOKEN", "")
+	if token == "" {
+		return nil, errors.New("No TMDB API Token provided")
+	}
+	api := &API{
+		token: token,
+	}
+	err := api.getConfig()
+	if err != nil {
+		return nil, errors.Wrap(err, "api.getConfig")
+	}
+	return api, nil
+}

tmdb/config.go

@@ -20,13 +20,17 @@ type Image struct {
 	StillSizes    []string `json:"still_sizes"`
 }
 
-func GetConfig(token string) (*Config, error) {
+func (api *API) getConfig() error {
-	url := "https://api.themoviedb.org/3/configuration"
+	url := requestURL("configuration")
-	data, err := tmdbGet(url, token)
+	data, err := api.get(url)
 	if err != nil {
-		return nil, errors.Wrap(err, "tmdbGet")
+		return errors.Wrap(err, "api.get")
 	}
 	config := Config{}
-	json.Unmarshal(data, &config)
+	err = json.Unmarshal(data, &config)
-	return &config, nil
+	if err != nil {
+		return errors.Wrap(err, "json.Unmarshal")
+	}
+	api.Config = &config
+	return nil
 }

tmdb/credits.go

@@ -2,7 +2,7 @@ package tmdb
 
 import (
 	"encoding/json"
-	"fmt"
+	"strconv"
 
 	"github.com/pkg/errors"
 )
@@ -42,11 +42,12 @@ type Crew struct {
 	Job          string `json:"job"`
 }
 
-func GetCredits(movieid int32, token string) (*Credits, error) {
+func (api *API) GetCredits(movieid int64) (*Credits, error) {
-	url := fmt.Sprintf("https://api.themoviedb.org/3/movie/%v/credits?language=en-US", movieid)
+	path := []string{"movie", strconv.FormatInt(movieid, 10), "credits"}
-	data, err := tmdbGet(url, token)
+	url := buildURL(path, nil)
+	data, err := api.get(url)
 	if err != nil {
-		return nil, errors.Wrap(err, "tmdbGet")
+		return nil, errors.Wrap(err, "api.get")
 	}
 	credits := Credits{}
 	json.Unmarshal(data, &credits)

tmdb/doc.go

@@ -0,0 +1,160 @@
+// Package tmdb provides a client for The Movie Database (TMDB) API.
+//
+// This package offers a clean interface for interacting with TMDB's REST API,
+// including automatic rate limiting, retry logic, and convenient URL building utilities.
+//
+// # Getting Started
+//
+// First, create an API connection using your TMDB API token:
+//
+//	api, err := tmdb.NewAPIConnection()
+//	if err != nil {
+//		log.Fatal(err)
+//	}
+//
+// The token is read from the TMDB_TOKEN environment variable.
+//
+// # Making Requests
+//
+// The package provides clean URL building functions to construct API requests:
+//
+//	// Simple endpoint
+//	url := tmdb.requestURL("movie", "550")
+//	// Result: "https://api.themoviedb.org/3/movie/550"
+//
+//	// With query parameters
+//	url := tmdb.buildURL([]string{"search", "movie"}, map[string]string{
+//		"query": "Inception",
+//		"page":  "1",
+//	})
+//	// Result: "https://api.themoviedb.org/3/search/movie?language=en-US&page=1&query=Inception"
+//
+// All requests made with buildURL automatically include "language=en-US" by default.
+//
+// # Rate Limiting
+//
+// TMDB has rate limits around 40 requests per second. This package implements
+// automatic retry logic with exponential backoff:
+//
+//   - Initial backoff: 1 second
+//   - Exponential growth: 1s → 2s → 4s → 8s → 16s → 32s (max)
+//   - Maximum retries: 3 attempts
+//   - Respects Retry-After header when provided by the API
+//
+// Example of rate-limited request:
+//
+//	data, err := api.get(url)
+//	if err != nil {
+//		// Will return error only after exhausting all retries
+//		log.Printf("Request failed: %v", err)
+//	}
+//
+// # Searching for Movies
+//
+// Search for movies by title:
+//
+//	results, err := tmdb.SearchMovies(token, "Fight Club", false, 1)
+//	if err != nil {
+//		log.Fatal(err)
+//	}
+//
+//	for _, movie := range results.Results {
+//		fmt.Printf("%s %s\n", movie.Title, movie.ReleaseYear())
+//		fmt.Printf("Poster: %s\n", movie.GetPoster(&api.Image, "w500"))
+//	}
+//
+// # Getting Movie Details
+//
+// Fetch detailed information about a specific movie:
+//
+//	movie, err := tmdb.GetMovie(550, token)
+//	if err != nil {
+//		log.Fatal(err)
+//	}
+//
+//	fmt.Printf("Title: %s\n", movie.Title)
+//	fmt.Printf("Overview: %s\n", movie.Overview)
+//	fmt.Printf("Release Date: %s\n", movie.ReleaseDate)
+//	fmt.Printf("IMDb ID: %s\n", movie.IMDbID)
+//
+// # Getting Credits
+//
+// Retrieve cast and crew information:
+//
+//	credits, err := tmdb.GetCredits(550, token)
+//	if err != nil {
+//		log.Fatal(err)
+//	}
+//
+//	fmt.Println("Cast:")
+//	for _, actor := range credits.Cast {
+//		fmt.Printf("  %s as %s\n", actor.Name, actor.Character)
+//	}
+//
+//	fmt.Println("\nCrew:")
+//	for _, member := range credits.Crew {
+//		if member.Job == "Director" {
+//			fmt.Printf("  Director: %s\n", member.Name)
+//		}
+//	}
+//
+// # Image URLs
+//
+// The API configuration includes base URLs for images. Use helper methods to
+// construct full image URLs:
+//
+//	posterURL := movie.GetPoster(&api.Image, "w500")
+//	// Available sizes: "w92", "w154", "w185", "w342", "w500", "w780", "original"
+//
+// # Error Handling
+//
+// The package returns wrapped errors for easy debugging:
+//
+//	data, err := api.get(url)
+//	if err != nil {
+//		if strings.Contains(err.Error(), "rate limit exceeded") {
+//			// Handle rate limiting
+//		} else if strings.Contains(err.Error(), "unexpected status code") {
+//			// Handle HTTP errors
+//		} else {
+//			// Handle network errors
+//		}
+//	}
+//
+// Common error scenarios:
+//   - "rate limit exceeded: maximum retries reached" - All retry attempts exhausted
+//   - "unexpected status code: 401" - Invalid API token
+//   - "unexpected status code: 404" - Resource not found
+//   - Network errors for connectivity issues
+//
+// # Environment Variables
+//
+// The package uses the following environment variable:
+//
+//   - TMDB_TOKEN: Your TMDB API access token (required)
+//
+// Obtain an API token from: https://www.themoviedb.org/settings/api
+//
+// # Best Practices
+//
+// 1. Reuse the API connection instead of creating new ones for each request
+// 2. Use buildURL for consistency and automatic language parameter injection
+// 3. Handle rate limit errors gracefully - they indicate temporary service issues
+// 4. Cache API responses when appropriate to reduce API calls
+// 5. Use specific image sizes instead of "original" to save bandwidth
+//
+// # API Documentation
+//
+// For complete TMDB API documentation, visit:
+// https://developer.themoviedb.org/docs
+//
+// # Rate Limiting Details
+//
+// From TMDB's documentation:
+// "While our legacy rate limits have been disabled for some time, we do still
+// have some upper limits to help mitigate needlessly high bulk scraping. They
+// sit somewhere in the 40 requests per second range."
+//
+// This package automatically handles rate limiting with exponential backoff to
+// ensure respectful API usage.
+package tmdb

tmdb/go.mod

@@ -2,4 +2,7 @@ module git.haelnorr.com/h/golib/tmdb
 
 go 1.25.5
 
-require github.com/pkg/errors v0.9.1
+require (
+	git.haelnorr.com/h/golib/env v0.9.1
+	github.com/pkg/errors v0.9.1
+)

tmdb/go.sum

@@ -1,2 +1,4 @@
+git.haelnorr.com/h/golib/env v0.9.1 h1:2Vsj+mJKnO5f1Md1GO5v9ggLN5zWa0baCewcSHTjoNY=
+git.haelnorr.com/h/golib/env v0.9.1/go.mod h1:glUQVdA1HMKX1avTDyTyuhcr36SSxZtlJxKDT5KTztg=
 github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
 github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=

tmdb/movie.go

@@ -2,7 +2,7 @@ package tmdb
 
 import (
 	"encoding/json"
-	"fmt"
+	"strconv"
 
 	"github.com/pkg/errors"
 )
@@ -33,11 +33,12 @@ type Movie struct {
 	Video               bool                `json:"video"`
 }
 
-func GetMovie(id int32, token string) (*Movie, error) {
+func (api *API) GetMovie(movieid int64) (*Movie, error) {
-	url := fmt.Sprintf("https://api.themoviedb.org/3/movie/%v?language=en-US", id)
+	path := []string{"movie", strconv.FormatInt(movieid, 10)}
-	data, err := tmdbGet(url, token)
+	url := buildURL(path, nil)
+	data, err := api.get(url)
 	if err != nil {
-		return nil, errors.Wrap(err, "tmdbGet")
+		return nil, errors.Wrap(err, "api.get")
 	}
 	movie := Movie{}
 	json.Unmarshal(data, &movie)

tmdb/request.go

@@ -4,25 +4,113 @@ import (
 	"fmt"
 	"io"
 	"net/http"
+	"net/url"
+	"strings"
+	"time"
 
 	"github.com/pkg/errors"
 )
 
-func tmdbGet(url string, token string) ([]byte, error) {
+const baseURL string = "https://api.themoviedb.org"
-	req, err := http.NewRequest("GET", url, nil)
+const apiVer string = "3"
-	if err != nil {
+
-		return nil, errors.Wrap(err, "http.NewRequest")
+const (
-	}
+	maxRetries     = 3                // Maximum number of retry attempts for 429 responses
-	req.Header.Add("accept", "application/json")
+	initialBackoff = 1 * time.Second  // Initial backoff duration
-	req.Header.Add("Authorization", fmt.Sprintf("Bearer %s", token))
+	maxBackoff     = 32 * time.Second // Maximum backoff duration
-	res, err := http.DefaultClient.Do(req)
+)
-	if err != nil {
+
-		return nil, errors.Wrap(err, "http.DefaultClient.Do")
+// requestURL builds a clean API URL from path segments.
-	}
+// Example: requestURL("movie", "550") -> "https://api.themoviedb.org/3/movie/550"
-	defer res.Body.Close()
+// Example: requestURL("search", "movie") -> "https://api.themoviedb.org/3/search/movie"
-	body, err := io.ReadAll(res.Body)
+func requestURL(pathSegments ...string) string {
-	if err != nil {
+	path := strings.Join(pathSegments, "/")
-		return nil, errors.Wrap(err, "io.ReadAll")
+	return fmt.Sprintf("%s/%s/%s", baseURL, apiVer, path)
-	}
+}
-	return body, nil
+
+// buildURL is a convenience function that builds a URL with query parameters.
+// Example: buildURL([]string{"search", "movie"}, map[string]string{"query": "Inception", "page": "1"})
+func buildURL(pathSegments []string, params map[string]string) string {
+	baseURL := requestURL(pathSegments...)
+	if params == nil {
+		params = map[string]string{}
+	}
+	params["language"] = "en-US"
+	values := url.Values{}
+	for key, val := range params {
+		values.Add(key, val)
+	}
+
+	return fmt.Sprintf("%s?%s", baseURL, values.Encode())
+}
+
+// get performs a GET request to the TMDB API with proper authentication headers
+// and automatic retry logic with exponential backoff for rate limiting (429 responses).
+//
+// The TMDB API has rate limits around 40 requests per second. This function
+// implements a courtesy backoff mechanism that:
+//   - Retries up to maxRetries times on 429 responses
+//   - Uses exponential backoff: 1s, 2s, 4s, 8s, etc. (up to maxBackoff)
+//   - Returns an error if max retries are exceeded
+//
+// The url parameter should be the full URL (can be built using requestURL or buildURL).
+func (api *API) get(url string) ([]byte, error) {
+	backoff := initialBackoff
+
+	for attempt := 0; attempt <= maxRetries; attempt++ {
+		req, err := http.NewRequest("GET", url, nil)
+		if err != nil {
+			return nil, errors.Wrap(err, "http.NewRequest")
+		}
+		req.Header.Add("accept", "application/json")
+		req.Header.Add("Authorization", fmt.Sprintf("Bearer %s", api.token))
+
+		res, err := http.DefaultClient.Do(req)
+		if err != nil {
+			return nil, errors.Wrap(err, "http.DefaultClient.Do")
+		}
+
+		// Check for rate limiting (429 Too Many Requests)
+		if res.StatusCode == http.StatusTooManyRequests {
+			res.Body.Close()
+
+			// If we've exhausted retries, return an error
+			if attempt >= maxRetries {
+				return nil, errors.New("rate limit exceeded: maximum retries reached")
+			}
+
+			// Check for Retry-After header first (respect server's guidance)
+			if retryAfter := res.Header.Get("Retry-After"); retryAfter != "" {
+				if duration, err := time.ParseDuration(retryAfter + "s"); err == nil {
+					backoff = duration
+				}
+			}
+
+			// Apply exponential backoff: 1s, 2s, 4s, 8s, etc.
+			if backoff > maxBackoff {
+				backoff = maxBackoff
+			}
+
+			time.Sleep(backoff)
+
+			// Double the backoff for next iteration
+			backoff *= 2
+
+			continue
+		}
+
+		// For other error status codes, return an error
+		if res.StatusCode != http.StatusOK {
+			return nil, errors.Errorf("unexpected status code: %d", res.StatusCode)
+		}
+
+		// Success - read and return body
+		body, err := io.ReadAll(res.Body)
+		if err != nil {
+			return nil, errors.Wrap(err, "io.ReadAll")
+		}
+		return body, nil
+	}
+
+	return nil, errors.Errorf("max retries (%d) exceeded due to rate limiting (HTTP 429)", maxRetries)
 }

tmdb/request_test.go

@@ -0,0 +1,360 @@
+package tmdb
+
+import (
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestRequestURL(t *testing.T) {
+	tests := []struct {
+		name     string
+		segments []string
+		want     string
+	}{
+		{
+			name:     "single segment",
+			segments: []string{"configuration"},
+			want:     "https://api.themoviedb.org/3/configuration",
+		},
+		{
+			name:     "two segments",
+			segments: []string{"search", "movie"},
+			want:     "https://api.themoviedb.org/3/search/movie",
+		},
+		{
+			name:     "movie with id",
+			segments: []string{"movie", "550"},
+			want:     "https://api.themoviedb.org/3/movie/550",
+		},
+		{
+			name:     "movie with id and credits",
+			segments: []string{"movie", "550", "credits"},
+			want:     "https://api.themoviedb.org/3/movie/550/credits",
+		},
+		{
+			name:     "no segments",
+			segments: []string{},
+			want:     "https://api.themoviedb.org/3/",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := requestURL(tt.segments...)
+			if got != tt.want {
+				t.Errorf("requestURL() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestBuildURL(t *testing.T) {
+	tests := []struct {
+		name     string
+		segments []string
+		params   map[string]string
+		want     string
+	}{
+		{
+			name:     "no params",
+			segments: []string{"movie", "550"},
+			params:   nil,
+			want:     "https://api.themoviedb.org/3/movie/550?language=en-US",
+		},
+		{
+			name:     "with query param",
+			segments: []string{"search", "movie"},
+			params: map[string]string{
+				"query": "Inception",
+			},
+			want: "https://api.themoviedb.org/3/search/movie?language=en-US&query=Inception",
+		},
+		{
+			name:     "multiple params",
+			segments: []string{"search", "movie"},
+			params: map[string]string{
+				"query":         "Fight Club",
+				"page":          "2",
+				"include_adult": "false",
+			},
+			// Note: URL params can be in any order, so we check contains instead
+			want: "https://api.themoviedb.org/3/search/movie?",
+		},
+		{
+			name:     "params with special characters",
+			segments: []string{"search", "movie"},
+			params: map[string]string{
+				"query": "The Matrix",
+			},
+			want: "https://api.themoviedb.org/3/search/movie?",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := buildURL(tt.segments, tt.params)
+			if !strings.HasPrefix(got, tt.want) {
+				t.Errorf("buildURL() = %v, want prefix %v", got, tt.want)
+			}
+			// Check that all params are present (checking keys, values may be URL encoded)
+			for key := range tt.params {
+				if !strings.Contains(got, key+"=") {
+					t.Errorf("buildURL() missing param key %s in %v", key, got)
+				}
+			}
+			// Check that language is always added
+			if !strings.Contains(got, "language=en-US") {
+				t.Errorf("buildURL() missing default language param in %v", got)
+			}
+		})
+	}
+}
+
+func TestAPIGet_Success(t *testing.T) {
+	// Create a test server that returns 200 OK
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// Verify headers
+		if r.Header.Get("accept") != "application/json" {
+			t.Errorf("missing or incorrect accept header")
+		}
+		if !strings.HasPrefix(r.Header.Get("Authorization"), "Bearer ") {
+			t.Errorf("missing or incorrect Authorization header")
+		}
+
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte(`{"success": true}`))
+	}))
+	defer server.Close()
+
+	api := &API{token: "test-token"}
+	body, err := api.get(server.URL)
+	if err != nil {
+		t.Errorf("get() unexpected error: %v", err)
+	}
+
+	expected := `{"success": true}`
+	if string(body) != expected {
+		t.Errorf("get() = %v, want %v", string(body), expected)
+	}
+}
+
+func TestAPIGet_RateLimitRetry(t *testing.T) {
+	attemptCount := 0
+
+	// Create a test server that returns 429 twice, then 200
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		attemptCount++
+		if attemptCount <= 2 {
+			w.WriteHeader(http.StatusTooManyRequests)
+			return
+		}
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte(`{"success": true}`))
+	}))
+	defer server.Close()
+
+	api := &API{token: "test-token"}
+	start := time.Now()
+	body, err := api.get(server.URL)
+	elapsed := time.Since(start)
+
+	if err != nil {
+		t.Errorf("get() unexpected error: %v", err)
+	}
+
+	if attemptCount != 3 {
+		t.Errorf("expected 3 attempts, got %d", attemptCount)
+	}
+
+	// Should have waited at least 1s + 2s = 3s total
+	if elapsed < 3*time.Second {
+		t.Errorf("expected backoff delay, got %v", elapsed)
+	}
+
+	expected := `{"success": true}`
+	if string(body) != expected {
+		t.Errorf("get() = %v, want %v", string(body), expected)
+	}
+}
+
+func TestAPIGet_RateLimitExceeded(t *testing.T) {
+	attemptCount := 0
+
+	// Create a test server that always returns 429
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		attemptCount++
+		w.WriteHeader(http.StatusTooManyRequests)
+	}))
+	defer server.Close()
+
+	api := &API{token: "test-token"}
+	_, err := api.get(server.URL)
+
+	if err == nil {
+		t.Error("get() expected error, got nil")
+	}
+
+	if !strings.Contains(err.Error(), "rate limit exceeded") {
+		t.Errorf("get() expected rate limit error, got: %v", err)
+	}
+
+	// Should have attempted maxRetries + 1 times (initial + retries)
+	expectedAttempts := maxRetries + 1
+	if attemptCount != expectedAttempts {
+		t.Errorf("expected %d attempts, got %d", expectedAttempts, attemptCount)
+	}
+}
+
+func TestAPIGet_RetryAfterHeader(t *testing.T) {
+	attemptCount := 0
+
+	// Create a test server that returns 429 with Retry-After header
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		attemptCount++
+		if attemptCount == 1 {
+			w.Header().Set("Retry-After", "2")
+			w.WriteHeader(http.StatusTooManyRequests)
+			return
+		}
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte(`{"success": true}`))
+	}))
+	defer server.Close()
+
+	api := &API{token: "test-token"}
+	start := time.Now()
+	body, err := api.get(server.URL)
+	elapsed := time.Since(start)
+
+	if err != nil {
+		t.Errorf("get() unexpected error: %v", err)
+	}
+
+	// Should have waited at least 2s as specified in Retry-After
+	if elapsed < 2*time.Second {
+		t.Errorf("expected at least 2s delay from Retry-After header, got %v", elapsed)
+	}
+
+	expected := `{"success": true}`
+	if string(body) != expected {
+		t.Errorf("get() = %v, want %v", string(body), expected)
+	}
+}
+
+func TestAPIGet_NonOKStatus(t *testing.T) {
+	tests := []struct {
+		name       string
+		statusCode int
+	}{
+		{"bad request", http.StatusBadRequest},
+		{"unauthorized", http.StatusUnauthorized},
+		{"forbidden", http.StatusForbidden},
+		{"not found", http.StatusNotFound},
+		{"internal server error", http.StatusInternalServerError},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				w.WriteHeader(tt.statusCode)
+			}))
+			defer server.Close()
+
+			api := &API{token: "test-token"}
+			_, err := api.get(server.URL)
+
+			if err == nil {
+				t.Error("get() expected error, got nil")
+			}
+
+			expectedError := fmt.Sprintf("unexpected status code: %d", tt.statusCode)
+			if !strings.Contains(err.Error(), expectedError) {
+				t.Errorf("get() expected error containing %q, got: %v", expectedError, err)
+			}
+		})
+	}
+}
+
+func TestAPIGet_NetworkError(t *testing.T) {
+	api := &API{token: "test-token"}
+	_, err := api.get("http://invalid-domain-that-does-not-exist.local")
+
+	if err == nil {
+		t.Error("get() expected error for invalid domain, got nil")
+	}
+
+	if !strings.Contains(err.Error(), "http.DefaultClient.Do") {
+		t.Errorf("get() expected network error, got: %v", err)
+	}
+}
+
+func TestAPIGet_InvalidURL(t *testing.T) {
+	api := &API{token: "test-token"}
+	_, err := api.get("://invalid-url")
+
+	if err == nil {
+		t.Error("get() expected error for invalid URL, got nil")
+	}
+
+	if !strings.Contains(err.Error(), "http.NewRequest") {
+		t.Errorf("get() expected URL parse error, got: %v", err)
+	}
+}
+
+func TestAPIGet_ReadBodyError(t *testing.T) {
+	// Create a test server that closes connection before body is read
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Length", "100")
+		w.WriteHeader(http.StatusOK)
+		// Don't write anything, causing a read error
+	}))
+	defer server.Close()
+
+	api := &API{token: "test-token"}
+	
+	// Note: This test may not always fail as expected due to how httptest works
+	// In real scenarios, network issues would cause io.ReadAll to fail
+	_, err := api.get(server.URL)
+	
+	// Just verify we got a response (this test is mainly for coverage)
+	if err != nil && !strings.Contains(err.Error(), "io.ReadAll") {
+		t.Logf("get() error (expected in some cases): %v", err)
+	}
+}
+
+// Benchmark tests
+func BenchmarkRequestURL(b *testing.B) {
+	for i := 0; i < b.N; i++ {
+		requestURL("movie", "550", "credits")
+	}
+}
+
+func BenchmarkBuildURL(b *testing.B) {
+	params := map[string]string{
+		"query": "Inception",
+		"page":  "1",
+	}
+	for i := 0; i < b.N; i++ {
+		buildURL([]string{"search", "movie"}, params)
+	}
+}
+
+func BenchmarkAPIGet(b *testing.B) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+		io.WriteString(w, `{"success": true}`)
+	}))
+	defer server.Close()
+
+	api := &API{token: "test-token"}
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		api.get(server.URL)
+	}
+}

tmdb/search.go

@@ -2,9 +2,9 @@ package tmdb
 
 import (
 	"encoding/json"
-	"fmt"
 	"net/url"
 	"path"
+	"strconv"
 
 	"github.com/pkg/errors"
 )
@@ -63,17 +63,19 @@ func (movie *ResultMovie) ReleaseYear() string {
 // 	return genres[:len(genres)-2]
 // }
 
-func SearchMovies(token string, query string, adult bool, page int) (*ResultMovies, error) {
+func (api *API) SearchMovies(query string, adult bool, page int64) (*ResultMovies, error) {
-	url := "https://api.themoviedb.org/3/search/movie" +
+	path := []string{"searc", "movie"}
-		fmt.Sprintf("?query=%s", url.QueryEscape(query)) +
+	params := map[string]string{
-		fmt.Sprintf("&include_adult=%t", adult) +
+		"query":         url.QueryEscape(query),
-		fmt.Sprintf("&page=%v", page) +
+		"include_adult": strconv.FormatBool(adult),
-		"&language=en-US"
+		"page":          strconv.FormatInt(page, 10),
-	response, err := tmdbGet(url, token)
+	}
+	url := buildURL(path, params)
+	data, err := api.get(url)
 	if err != nil {
-		return nil, errors.Wrap(err, "tmdbGet")
+		return nil, errors.Wrap(err, "api.get")
 	}
 	var results ResultMovies
-	json.Unmarshal(response, &results)
+	json.Unmarshal(data, &results)
 	return &results, nil
 }