Polishing documentation purged binaries

Author: abitofhelp

EXAMPLES/auth/quickstart/README.md

@@ -2,13 +2,14 @@
 
 ## Overview
 
-This example demonstrates the quickstart functionality of the ServiceLib auth package.
+This example demonstrates how to quickly set up authentication and authorization using the ServiceLib auth package. It shows the basic steps to create an auth instance, use auth middleware, and perform authorization checks.
 
 ## Features
 
-- **Feature 1**: Description of feature 1
-- **Feature 2**: Description of feature 2
-- **Feature 3**: Description of feature 3
+- **Auth Configuration**: Set up auth configuration with JWT secret key
+- **Auth Middleware**: Protect HTTP endpoints with auth middleware
+- **Authorization Checks**: Check if users are authorized to perform operations
+- **User Context**: Access user information from the request context
 
 ## Running the Example
 
@@ -20,36 +21,60 @@ go run main.go
 
 ## Code Walkthrough
 
-### Key Component 1
+### Auth Configuration and Instance Creation
 
-Description of the first key component in this example:
+This example starts by creating an auth configuration with a JWT secret key and then creating an auth instance:
 
-```
-// Code snippet for key component 1
+```go
+// Create a configuration
+config := auth.DefaultConfig()
+config.JWT.SecretKey = "your-secret-key-that-is-at-least-32-characters-long"
+
+// Create an auth instance
+authInstance, err := auth.New(ctx, config, logger)
+if err != nil {
+    logger.Fatal("Failed to create auth instance", zap.Error(err))
+}
 ```
 
-### Key Component 2
+### Auth Middleware
 
-Description of the second key component in this example:
+The example shows how to use the auth middleware to protect an HTTP endpoint:
 
-```
-// Code snippet for key component 2
+```go
+http.Handle("/", authInstance.Middleware()(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+    // Handler code
+})))
 ```
 
-### Key Component 3
+### Authorization Checks
 
-Description of the third key component in this example:
+The example demonstrates how to check if a user is authorized to perform an operation:
 
-```
-// Code snippet for key component 3
+```go
+// Check if the user is authorized to perform an operation
+authorized, err := authInstance.IsAuthorized(r.Context(), "read:resource")
+if err != nil {
+    http.Error(w, "Authorization error", http.StatusInternalServerError)
+    return
+}
+
+if !authorized {
+    http.Error(w, "Forbidden", http.StatusForbidden)
+    return
+}
 ```
 
 ## Expected Output
 
+When you run the example and access the HTTP endpoint with a valid JWT token that has the "read:resource" permission, you should see:
+
 ```
-Expected output of the example when run
+Hello, [user-id]
 ```
 
+Where [user-id] is the ID of the authenticated user. If the token is invalid or the user doesn't have the required permission, you'll see an error message.
+
 ## Related Examples
 
 

EXAMPLES/auth/quickstart/quickstart

@@ -2,13 +2,14 @@
 
 ## Overview
 
-This example demonstrates the config_integration functionality of the ServiceLib env package.
+This example demonstrates how to integrate environment variables with a configuration structure using the ServiceLib env package. It shows how to create a structured configuration object that loads its values from environment variables, with validation and type conversion.
 
 ## Features
 
-- **Feature 1**: Description of feature 1
-- **Feature 2**: Description of feature 2
-- **Feature 3**: Description of feature 3
+- **Configuration Structure**: Create a typed configuration structure to hold application settings
+- **Environment Variable Loading**: Load values from environment variables into the configuration structure
+- **Validation**: Validate configuration values for correctness
+- **Complex Types**: Handle complex types like slices from environment variables
 
 ## Running the Example
 
@@ -20,47 +21,116 @@ go run main.go
 
 ## Code Walkthrough
 
-### Key Component 1
+### AppConfig Structure
 
-Description of the first key component in this example:
+The AppConfig structure centralizes all configuration settings in one place:
 
+```go
+type AppConfig struct {
+    ServerPort  string   // Port the server will listen on (from SERVER_PORT)
+    DatabaseURL string   // Connection string for the database (from DATABASE_URL)
+    LogLevel    string   // Logging level: debug, info, warn, error (from LOG_LEVEL)
+    APIKey      string   // API key for external service authentication (from API_KEY)
+    Environment string   // Application environment: development, testing, staging, production (from APP_ENV)
+    Features    []string // Enabled features as a slice of strings (from comma-separated FEATURES)
+}
 ```
-// Code snippet for key component 1
-```
-
-### Key Component 2
 
-Description of the second key component in this example:
-
-```
-// Code snippet for key component 2
+### Loading Configuration
+
+The LoadConfig function retrieves values from environment variables and populates the AppConfig struct:
+
+```go
+func LoadConfig() AppConfig {
+    // Load features from a comma-separated environment variable
+    featuresStr := env.GetEnv("FEATURES", "basic,standard")
+    features := strings.Split(featuresStr, ",")
+
+    return AppConfig{
+        ServerPort:  env.GetEnv("SERVER_PORT", "8080"),
+        DatabaseURL: env.GetEnv("DATABASE_URL", "postgres://localhost:5432/mydb"),
+        LogLevel:    env.GetEnv("LOG_LEVEL", "info"),
+        APIKey:      env.GetEnv("API_KEY", ""),
+        Environment: env.GetEnv("APP_ENV", "development"),
+        Features:    features,
+    }
+}
 ```
 
-### Key Component 3
-
-Description of the third key component in this example:
-
-```
-// Code snippet for key component 3
+### Configuration Validation
+
+The Validate method checks the configuration values for correctness:
+
+```go
+func (c *AppConfig) Validate() []string {
+    var errors []string
+
+    // Check required values
+    if c.APIKey == "" {
+        errors = append(errors, "API_KEY environment variable is required")
+    }
+
+    // Validate log level
+    validLogLevels := map[string]bool{
+        "debug": true,
+        "info":  true,
+        "warn":  true,
+        "error": true,
+    }
+    if !validLogLevels[strings.ToLower(c.LogLevel)] {
+        errors = append(errors, fmt.Sprintf("Invalid log level: %s. Must be one of: debug, info, warn, error", c.LogLevel))
+    }
+
+    // Validate environment
+    validEnvs := map[string]bool{
+        "development": true,
+        "testing":     true,
+        "staging":     true,
+        "production":  true,
+    }
+    if !validEnvs[strings.ToLower(c.Environment)] {
+        errors = append(errors, fmt.Sprintf("Invalid environment: %s. Must be one of: development, testing, staging, production", c.Environment))
+    }
+
+    return errors
+}
 ```
 
 ## Expected Output
 
 ```
-Expected output of the example when run
+Environment Variables Configuration Integration Example
+=====================================================
+Server Port: 8080
+Database URL: postgres://localhost:5432/mydb
+Log Level: info
+Environment: development
+Features: [basic standard]
+Warning: API_KEY environment variable is not set
+
+Configuration Errors:
+- API_KEY environment variable is required
+
+Try running this example with different environment variables set:
+export SERVER_PORT=9090
+export DATABASE_URL="postgres://user:password@localhost:5432/mydb"
+export LOG_LEVEL="debug"
+export API_KEY="your-api-key"
+export APP_ENV="production"
+export FEATURES="basic,premium,advanced"
+go run EXAMPLES/env/config_integration_example.go
 ```
 
 ## Related Examples
 
-
-- [basic_usage](../basic_usage/README.md) - Related example for basic_usage
+- [basic_usage](../basic_usage/README.md) - Shows basic usage of environment variables
 
 ## Related Components
 
 - [env Package](../../../env/README.md) - The env package documentation.
+- [Config Package](../../../config/README.md) - The config package for more advanced configuration.
+- [Validation Package](../../../validation/README.md) - The validation package for input validation.
 - [Errors Package](../../../errors/README.md) - The errors package used for error handling.
-- [Context Package](../../../context/README.md) - The context package used for context handling.
-- [Logging Package](../../../logging/README.md) - The logging package used for logging.
 
 ## License
 

EXAMPLES/cache/basic_usage/basic_usage

@@ -2,13 +2,14 @@
 
 ## Overview
 
-This example demonstrates the auth_configuration functionality of the ServiceLib graphql package.
+This example demonstrates how to configure the authentication service for use with GraphQL in the ServiceLib library. It shows how to set up JWT authentication settings and configure middleware to bypass authentication for specific endpoints.
 
 ## Features
 
-- **Feature 1**: Description of feature 1
-- **Feature 2**: Description of feature 2
-- **Feature 3**: Description of feature 3
+- **JWT Configuration**: Configure JWT token settings including secret key, issuer, and token duration
+- **Middleware Skip Paths**: Set up paths that bypass authentication middleware
+- **Auth Service Initialization**: Initialize the auth service with the configuration
+- **GraphQL Integration**: Prepare auth service for use with GraphQL endpoints
 
 ## Running the Example
 
@@ -20,34 +21,74 @@ go run main.go
 
 ## Code Walkthrough
 
-### Key Component 1
+### Auth Configuration Setup
 
-Description of the first key component in this example:
+The example shows how to create and configure the auth service with JWT settings:
 
-```
-// Code snippet for key component 1
+```go
+// Create a configuration for the auth service
+authConfig := auth.DefaultConfig()
+authConfig.JWT.SecretKey = "your-secret-key"
+authConfig.JWT.Issuer = "your-service"
+authConfig.JWT.TokenDuration = 24 * time.Hour
+authConfig.Middleware.SkipPaths = []string{"/health", "/metrics", "/playground"}
 ```
 
-### Key Component 2
+### Auth Service Initialization
 
-Description of the second key component in this example:
+The example demonstrates how to initialize the auth service with the configuration:
 
-```
-// Code snippet for key component 2
+```go
+// Initialize the auth service
+authService, err := auth.New(ctx, authConfig, logger)
+if err != nil {
+    fmt.Printf("Error initializing auth service: %v\n", err)
+    return
+}
 ```
 
-### Key Component 3
+### GraphQL Integration Considerations
 
-Description of the third key component in this example:
+The example specifically configures the auth service for GraphQL by:
 
-```
-// Code snippet for key component 3
-```
+1. Setting up skip paths for GraphQL-specific endpoints like `/playground`
+2. Configuring JWT settings appropriate for GraphQL authentication
+3. Preparing the auth service for integration with GraphQL resolvers
 
 ## Expected Output
 
+When you run the example, you should see output similar to:
+
 ```
-Expected output of the example when run
+Example: Configuring auth service for GraphQL
+
+Step 1: Configure the auth service
+
+        authConfig := auth.DefaultConfig()
+        authConfig.JWT.SecretKey = cfg.Auth.JWT.SecretKey
+        authConfig.JWT.Issuer = cfg.Auth.JWT.Issuer
+        authConfig.JWT.TokenDuration = cfg.Auth.JWT.TokenDuration
+        authConfig.Middleware.SkipPaths = []string{"/health", "/metrics", "/playground"}
+
+
+Step 2: Initialize the auth service
+
+        authService, err := auth.New(ctx, authConfig, logger)
+        if err != nil {
+                return nil, fmt.Errorf("failed to initialize auth service: %w", err)
+        }
+
+
+Auth service configured successfully!
+JWT Issuer: your-service
+Token Duration: 24h0m0s
+Skip Paths: [/health /metrics /playground]
+
+The auth service provides:
+- JWT token generation and validation
+- Middleware for authenticating HTTP requests
+- Functions for checking authorization
+- Context utilities for working with user information
 ```
 
 ## Related Examples