rhales 0.3.0 → 0.5.3

data/generate-json-schemas.ts

@@ -0,0 +1,158 @@
+#!/usr/bin/env -S pnpm exec tsx
+
+/**
+ * Generate JSON Schemas and TypeScript types from Zod configuration schemas
+ *
+ * Usage:
+ *   pnpm exec tsx scripts/generate-json-schemas.ts           # Generate main schema + types
+ *   pnpm exec tsx scripts/generate-json-schemas.ts --openapi # Include OpenAPI schemas
+ *   pnpm exec tsx scripts/generate-json-schemas.ts --watch   # Watch mode (future)
+ *
+ * NOTE: The `-S` flag in the hasbang allows `env` to handle multiple arguments.
+ */
+
+import { writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { z } from 'zod/v4';
+import { configSchema as mutableConfigSchema } from '../schemas/config/mutable';
+import { configSchema as staticConfigSchema } from '../schemas/config/static';
+import { configSchema as runtimeConfigSchema } from '../schemas/config/runtime';
+
+const ONETIME_HOME = process.env.ONETIME_HOME || process.cwd();
+
+const OUTPUT_MAIN_SCHEMA = join(ONETIME_HOME, 'public/web/dist/schemas/runtime.schema.json');
+const OUTPUT_SCHEMAS_DIR = join(ONETIME_HOME, 'etc/schemas');
+
+/**
+ * Generate individual JSON schema files
+ */
+function generateIndividualSchemas(): void {
+  mkdirSync(OUTPUT_SCHEMAS_DIR, { recursive: true });
+
+  const schemas = [
+    {
+      schema: staticConfigSchema,
+      name: 'config.schema',
+      description: 'Static configuration settings loaded from config.yaml',
+    },
+    {
+      schema: mutableConfigSchema,
+      name: 'mutable.schema',
+      description: 'Dynamic mutable config loaded from mutable.yaml',
+    },
+    {
+      schema: runtimeConfigSchema,
+      name: 'runtime.schema',
+      description: 'Combined configuration schema for both static and mutable config',
+    },
+  ];
+
+  schemas.forEach(({ schema, name, description }) => {
+    const jsonSchema = z.toJSONSchema(schema, {
+      target: 'draft-2020-12',
+      unrepresentable: 'any',
+      cycles: 'ref',
+      reused: 'inline',
+    });
+
+    const schemaWithMeta = {
+      $schema: 'https://json-schema.org/draft/2020-12/schema',
+      $id: `https://onetimesecret.com/schemas/${name}.json`,
+      title: name
+        .split('-')
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(' '),
+      description,
+      ...jsonSchema,
+    };
+
+    const outputPath = join(OUTPUT_SCHEMAS_DIR, `${name}.json`);
+    writeFileSync(outputPath, JSON.stringify(schemaWithMeta, null, 2) + '\n');
+    console.log(`Generated: ${outputPath}`);
+  });
+}
+
+/**
+ * Generate main configuration schema as YAML
+ */
+function generateMainSchema(): void {
+  const jsonSchema = z.toJSONSchema(staticConfigSchema, {
+    target: 'draft-2020-12',
+    unrepresentable: 'any',
+    cycles: 'ref',
+    reused: 'inline',
+  });
+
+  const schemaWithMeta = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $id: 'https://onetimesecret.com/schemas/config.schema.json',
+    title: 'OneTimeSecret Configuration',
+    description: 'Configuration schema for OneTimeSecret application',
+    ...jsonSchema,
+  };
+
+  mkdirSync(join(OUTPUT_MAIN_SCHEMA, '..'), { recursive: true });
+  writeFileSync(OUTPUT_MAIN_SCHEMA, JSON.stringify(schemaWithMeta, null, 2) + '\n');
+  console.log(`Generated: ${OUTPUT_MAIN_SCHEMA}`);
+}
+
+/**
+ * Generate OpenAPI schemas (optional)
+ */
+function generateOpenAPISchemas(): void {
+  const schemas = [
+    { schema: staticConfigSchema, name: 'static' },
+    { schema: mutableConfigSchema, name: 'mutable' },
+    { schema: runtimeConfigSchema, name: 'runtime' },
+  ];
+
+  schemas.forEach(({ schema, name }) => {
+    const openAPISchema = z.toJSONSchema(schema, {
+      target: 'draft-7',
+      unrepresentable: 'any',
+      cycles: 'ref',
+      reused: 'ref',
+    });
+
+    const schemaWithMeta = {
+      title: name
+        .split('-')
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(' '),
+      description: `OpenAPI schema for ${name}`,
+      ...openAPISchema,
+    };
+
+    const outputPath = join(OUTPUT_SCHEMAS_DIR, `${name}.openapi.json`);
+    writeFileSync(outputPath, JSON.stringify(schemaWithMeta, null, 2) + '\n');
+    console.log(`Generated: ${outputPath}`);
+  });
+}
+
+/**
+ * Main execution
+ */
+function main(): void {
+  const includeOpenAPI = process.argv.includes('--openapi');
+  const watchMode = process.argv.includes('--watch');
+
+  if (watchMode) {
+    console.log('Watch mode not yet implemented');
+    return;
+  }
+
+  generateMainSchema();
+  generateIndividualSchemas();
+
+  if (includeOpenAPI) {
+    generateOpenAPISchemas();
+  }
+
+  console.log('Schema generation complete');
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}
+
+export { generateMainSchema, generateIndividualSchemas, generateOpenAPISchemas };

data/json_schemer_migration_summary.md

@@ -0,0 +1,172 @@
+# JSON Schema Migration Summary: json-schema → json_schemer
+
+## Migration Complete ✓
+
+Successfully migrated from `json-schema` gem to `json_schemer` for better JSON Schema Draft 2020-12 support.
+
+## Changes Made
+
+### 1. Dependency Update
+- **File**: `rhales.gemspec`
+- **Change**: Replaced `json-schema ~> 4.0` with `json_schemer ~> 2.3`
+- **Reason**: Better Draft 2020-12 support, modern API, superior performance
+
+### 2. Middleware Implementation
+- **File**: `lib/rhales/middleware/schema_validator.rb`
+- **Changes**:
+  - Replaced `require 'json-schema'` with `require 'json_schemer'`
+  - Updated `load_schema_cached` to create JSONSchemer validator objects
+  - Removed `$schema` and `$id` stripping logic (json_schemer handles this natively)
+  - Replaced `JSON::Validator.fully_validate` with `schema.validate(data).to_a`
+  - Added `format_errors` method for human-readable error messages
+  - Maintained backward-compatible error message format
+
+### 3. Test Updates
+- **Files**:
+  - `spec/rhales/middleware/schema_validator_spec.rb`
+  - `spec/rhales/integration/schema_validation_spec.rb`
+- **Changes**:
+  - Added `require 'fileutils'` where needed
+  - Added `require 'rack'` for Rack::Request
+  - All existing tests pass without modification to test logic
+
+### 4. Documentation
+- **File**: `CHANGELOG.md`
+- **Added**: Entry documenting the migration and performance improvements
+
+## Key Benefits
+
+### 1. JSON Schema Draft 2020-12 Support
+- Full support for latest schema standard
+- Native handling of `$schema` and `$id` fields
+- Better specification compliance
+
+### 2. Performance Improvement
+- **Before** (json-schema): ~2ms average validation time
+- **After** (json_schemer): ~0.047ms average validation time
+- **Improvement**: ~42x faster (98% reduction)
+
+### 3. Better Error Messages
+json_schemer provides structured error objects with:
+- `data_pointer`: JSON Pointer to the invalid data
+- `schema_pointer`: JSON Pointer to the schema rule
+- `type`: Type of validation error
+- `error`: Human-readable message
+- Full error context for debugging
+
+### 4. Modern API
+```ruby
+# Old (json-schema)
+errors = JSON::Validator.fully_validate(schema, data, version: :draft4)
+
+# New (json_schemer)
+validator = JSONSchemer.schema(schema)
+errors = validator.validate(data).to_a
+```
+
+## Error Message Examples
+
+### Type Mismatch
+```
+The property '/authenticated' of type string did not match the following type: boolean
+```
+
+### Missing Required Field
+```
+The property '/' is missing required field(s): id, email
+```
+
+### Enum Validation
+```
+The property '/role' must be one of: admin, user, guest
+```
+
+### Range Validation
+```
+The property '/age' must be >= 0
+The property '/age' must be <= 150
+```
+
+## Test Results
+
+### All Tests Pass
+```
+533 examples, 0 failures
+Finished in 0.30839 seconds
+```
+
+### Schema Validation Tests
+```
+26 examples, 0 failures
+- 20 middleware unit tests
+- 6 integration tests
+```
+
+### Performance Test
+```
+Average validation time: 0.0473 ms
+Validated 10,000 times in 0.4726 seconds
+Performance target: < 5ms ✓
+```
+
+## Compatibility
+
+### Schema Format
+No changes needed to existing schemas:
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://rhales.dev/schemas/example.json",
+  "type": "object",
+  "properties": { ... }
+}
+```
+
+### Middleware Configuration
+No changes needed to middleware setup:
+```ruby
+use Rhales::Middleware::SchemaValidator,
+  schemas_dir: './public/schemas',
+  fail_on_error: ENV['RACK_ENV'] == 'development'
+```
+
+### Error Handling
+Backward-compatible error message format maintained for existing error checks in tests and applications.
+
+## Files Modified
+
+1. `/Users/d/Projects/opensource/onetime/rhales/rhales.gemspec`
+2. `/Users/d/Projects/opensource/onetime/rhales/lib/rhales/middleware/schema_validator.rb`
+3. `/Users/d/Projects/opensource/onetime/rhales/spec/rhales/middleware/schema_validator_spec.rb`
+4. `/Users/d/Projects/opensource/onetime/rhales/spec/rhales/integration/schema_validation_spec.rb`
+5. `/Users/d/Projects/opensource/onetime/rhales/CHANGELOG.md`
+
+## Acceptance Criteria - All Met ✓
+
+- [x] `json_schemer` added to gemspec
+- [x] `json-schema` removed from gemspec
+- [x] Middleware updated to use json_schemer
+- [x] Error formatting updated for better messages
+- [x] All middleware tests passing (20/20)
+- [x] All integration tests passing (6/6)
+- [x] Demo schemas validate correctly
+- [x] Full test suite passes (533/533 examples)
+- [x] Performance maintained (< 0.05ms, well under 5ms target)
+- [x] CHANGELOG updated
+- [x] Backward-compatible error messages
+
+## Next Steps
+
+1. Deploy to staging environment
+2. Monitor validation performance metrics
+3. Consider leveraging json_schemer's additional features:
+   - Remote schema references ($ref to URLs)
+   - Custom format validators
+   - OpenAPI schema support
+   - Meta-schema validation
+
+## References
+
+- json_schemer: https://github.com/davishmcclurg/json_schemer
+- JSON Schema Draft 2020-12: https://json-schema.org/draft/2020-12/schema
+- Migration commit: feature/29-contract branch

data/lib/rhales/adapters/base_auth.rb

@@ -1,4 +1,6 @@
 # lib/rhales/adapters/base_auth.rb
+#
+# frozen_string_literal: true
 
 module Rhales
   module Adapters

data/lib/rhales/adapters/base_request.rb

@@ -1,4 +1,6 @@
 # lib/rhales/adapters/base_request.rb
+#
+# frozen_string_literal: true
 
 module Rhales
   module Adapters

data/lib/rhales/adapters/base_session.rb

@@ -1,4 +1,6 @@
 # lib/rhales/adapters/base_session.rb
+#
+# frozen_string_literal: true
 
 module Rhales
   module Adapters

data/lib/rhales/adapters.rb

@@ -0,0 +1,7 @@
+# lib/rhales/adapters.rb
+#
+# frozen_string_literal: true
+
+require_relative 'adapters/base_auth'
+require_relative 'adapters/base_session'
+require_relative 'adapters/base_request'

data/lib/rhales/configuration.rb

@@ -1,6 +1,117 @@
 # lib/rhales/configuration.rb
+#
+# frozen_string_literal: true
 
 module Rhales
+  # Hydration-specific configuration settings
+  #
+  # Controls how hydration scripts are injected into HTML templates.
+  # Supports multiple injection strategies for different performance characteristics:
+  #
+  # ## Traditional Strategies
+  # - `:late` (default) - injects before </body> tag (safest, backwards compatible)
+  # - `:early` - injects before detected mount points for improved performance
+  # - `:earliest` - injects in HTML head section for maximum performance
+  #
+  # ## Link-Based Strategies (API endpoints)
+  # - `:link` - basic link reference to API endpoint
+  # - `:prefetch` - browser prefetch for future page loads
+  # - `:preload` - high priority preload for current page
+  # - `:modulepreload` - ES module preloading
+  # - `:lazy` - intersection observer-based lazy loading
+  class HydrationConfiguration
+    VALID_STRATEGIES = [:late, :early, :earliest, :link, :prefetch, :preload, :modulepreload, :lazy].freeze
+    LINK_BASED_STRATEGIES = [:link, :prefetch, :preload, :modulepreload, :lazy].freeze
+    DEFAULT_API_CACHE_TTL = 300  # 5 minutes
+
+    # Injection strategy - one of VALID_STRATEGIES
+    attr_accessor :injection_strategy
+
+    # Array of CSS selectors to detect frontend mount points
+    attr_accessor :mount_point_selectors
+
+    # Whether to fallback to late injection when no mount points detected
+    attr_accessor :fallback_to_late
+
+    # Whether to fallback to late injection when early injection is unsafe
+    attr_accessor :fallback_when_unsafe
+
+    # Disable early injection for specific templates (array of template names)
+    attr_accessor :disable_early_for_templates
+
+    # API endpoint configuration for link-based strategies
+    attr_accessor :api_endpoint_enabled, :api_endpoint_path
+
+    # Link tag configuration
+    attr_accessor :link_crossorigin
+
+    # Module export configuration for :modulepreload strategy
+    attr_accessor :module_export_enabled
+
+    # Lazy loading configuration
+    attr_accessor :lazy_mount_selector
+
+    # Data attribute reflection system
+    attr_accessor :reflection_enabled
+
+    # Caching configuration for API endpoints
+    attr_accessor :api_cache_enabled, :api_cache_ttl
+
+    # CORS configuration for API endpoints
+    attr_accessor :cors_enabled, :cors_origin
+
+    def initialize
+      # Traditional strategy settings
+      @injection_strategy = :late
+      @mount_point_selectors = ['#app', '#root', '[data-rsfc-mount]', '[data-mount]']
+      @fallback_to_late = true
+      @fallback_when_unsafe = true
+      @disable_early_for_templates = []
+
+      # API endpoint settings
+      @api_endpoint_enabled = false
+      @api_endpoint_path = '/api/hydration'
+
+      # Link tag settings
+      @link_crossorigin = true
+
+      # Module export settings
+      @module_export_enabled = false
+
+      # Lazy loading settings
+      @lazy_mount_selector = '#app'
+
+      # Reflection system settings
+      @reflection_enabled = true
+
+      # Caching settings
+      @api_cache_enabled = false
+      @api_cache_ttl = DEFAULT_API_CACHE_TTL
+
+      # CORS settings
+      @cors_enabled = false
+      @cors_origin = '*'
+    end
+
+    # Validate the injection strategy
+    def injection_strategy=(strategy)
+      unless VALID_STRATEGIES.include?(strategy)
+        raise ArgumentError, "Invalid injection strategy: #{strategy}. Valid options: #{VALID_STRATEGIES.join(', ')}"
+      end
+      @injection_strategy = strategy
+    end
+
+    # Check if current strategy is link-based
+    def link_based_strategy?
+      LINK_BASED_STRATEGIES.include?(@injection_strategy)
+    end
+
+    # Check if API endpoints should be enabled
+    def api_endpoints_required?
+      link_based_strategy? || @api_endpoint_enabled
+    end
+  end
+
   # Configuration management for Rhales library
   #
   # Provides a clean, testable alternative to global configuration access.
@@ -31,6 +142,21 @@ module Rhales
     # Performance settings
     attr_accessor :cache_parsed_templates, :cache_ttl
 
+    # Hydration settings
+    attr_accessor :hydration
+
+    # Schema validation settings
+    attr_accessor :enable_schema_validation, :fail_on_validation_error, :schemas_dir
+
+    # JSON response settings
+    attr_accessor :enable_json_responder, :json_responder_include_metadata
+
+    # Logging settings
+    attr_accessor :allowed_unescaped_variables
+
+    # Hydration mismatch reporting settings
+    attr_accessor :hydration_mismatch_format, :hydration_authority
+
     def initialize
       # Set sensible defaults
       @default_locale         = 'en'
@@ -47,6 +173,26 @@ module Rhales
       @site_ssl_enabled       = false
       @cache_parsed_templates = true
       @cache_ttl              = 3600 # 1 hour
+      @hydration              = HydrationConfiguration.new
+
+      # Schema validation defaults
+      @enable_schema_validation = true
+      @fail_on_validation_error = false # Set by environment in middleware
+      @schemas_dir              = './public/schemas' # Default to implementing project's public directory
+
+      # JSON responder defaults
+      @enable_json_responder            = true
+      @json_responder_include_metadata  = false
+
+      # Logging defaults
+      @allowed_unescaped_variables      = []
+
+      # Hydration mismatch reporting defaults
+      @hydration_mismatch_format        = :compact  # :compact, :multiline, :sidebyside, :json
+      @hydration_authority              = :schema   # :schema or :data
+
+      # Yield to block for configuration if provided
+      yield(self) if block_given?
     end
 
     # Build API base URL from site configuration
@@ -86,7 +232,7 @@ module Rhales
         'worker-src' => ["'self'"],
         'manifest-src' => ["'self'"],
         'prefetch-src' => ["'self'"],
-        'upgrade-insecure-requests' => []
+        'upgrade-insecure-requests' => [],
       }.freeze
     end
 
@@ -140,6 +286,20 @@ module Rhales
       yield(configuration) if block_given?
       configuration.validate!
       configuration.freeze!
+
+      # Debug log the configuration (guard against stale test mocks)
+      if Rhales.logger
+        require_relative 'utils/logging_helpers'
+        extend Rhales::Utils::LoggingHelpers
+
+        log_with_metadata(Rhales.logger, :debug, 'Rhales configured',
+          hydration_mismatch_format: configuration.hydration_mismatch_format,
+          hydration_authority: configuration.hydration_authority,
+          enable_schema_validation: configuration.enable_schema_validation,
+          fail_on_validation_error: configuration.fail_on_validation_error
+        )
+      end
+
       configuration
     end