🎛️ Stomp Base

ja README

A modern Rails engine that provides a beautiful, component-based admin interface and Rails console for your applications.

The name "stomp_base" comes from the snowboarding term "stomp", which means a perfect landing - a flawless, solid touchdown after a jump or trick. Just as a perfect stomp represents complete control and successful execution in snowboarding, this gem aims to provide the solid foundation and perfect support for the complete execution of your Rails projects.

• 📊 Dashboard: Real-time Rails application statistics and system information
• 💻 Browser Console: Execute Ruby code directly in your Rails environment with enhanced security
• 🎨 Modern UI: Built with View Components for a responsive, beautiful interface
• 🔧 Component-Based: Modular View Components for easy customization and extension
• 📖 Lookbook Integration: Component development and documentation with Lookbook
• 🌐 Multi-language Support: English and Japanese interface
• 🔧 Easy Integration: Simple gem installation and mounting process
• 🔐 Built-in Authentication: Simple authentication options (Basic Auth, API keys, Custom)
• ⚡ Stimulus Controllers: Modern JavaScript interactions with Stimulus

• View Components: For reusable, testable view components
• Stimulus: For JavaScript interactions
• Lookbook: For component development and documentation
• Turbo: For fast, modern web navigation

Add this line to your application's Gemfile:

gem 'stomp_base'

Then, execute:

bundle install

After installing the gem, you need to:

1. Mount the engine in your routes.rb file:

Rails.application.routes.draw do
  mount StompBase::Engine => "/stomp_base"
end

2. Install View Component (automatically included as dependency): The gem includes View Component as a dependency, so no additional setup is required.

StompBase automatically works with API-only Rails applications! The engine detects when the asset pipeline is not available and configures static asset serving automatically.

No additional configuration needed - StompBase will:

• Detect API-only mode (config.api_only = true)
• Automatically serve CSS assets via ActionDispatch::Static middleware
• Display helpful warnings if public file server is disabled

If you encounter styling issues in an API-only app, ensure public file server is enabled:

# config/application.rb or config/environments/development.rb
config.public_file_server.enabled = true

Alternatively, you can enable ActionView and the asset pipeline:

# config/application.rb
require "action_view/railtie"
# Remove or comment out: config.api_only = true

Visit /stomp_base in your browser to access the admin dashboard.

In development mode, you can access Lookbook for component development and documentation:

rails server
# Visit http://localhost:3000/lookbook

You can configure the language in an initializer file (config/initializers/stomp_base.rb):

# Set to Japanese
StompBase.configure do |config|
  config.locale = :ja
end

# Or set directly
StompBase.locale = :ja

# Default is English (:en)
StompBase.configure do |config|
  config.locale = :en
end

Stomp Base includes built-in authentication features that can be easily configured:

# config/initializers/stomp_base.rb
StompBase.configure do |config|
  config.locale = :ja
  
  config.enable_authentication(
    method: :basic_auth,
    username: 'admin',
    password: 'your_secure_password'
  )
end

# config/initializers/stomp_base.rb
StompBase.configure do |config|
  config.enable_authentication(
    method: :api_key,
    keys: ['your-api-key-1', 'your-api-key-2']
  )
end

# config/initializers/stomp_base.rb
StompBase.configure do |config|
  config.enable_authentication(
    method: :custom,
    authenticator: ->(request, params) {
      # Your custom authentication logic
      request.headers['Authorization'] == 'Bearer your-token'
    }
  )
end

# config/initializers/stomp_base.rb
StompBase.configure do |config|
  config.disable_authentication
end

For more detailed authentication configuration examples, see the Authentication Details section below.

Available locales:
- `:en` - English (default)
- `:ja` - Japanese (日本語)

### Accessing the Interface

- Dashboard: `/stomp_base/` or `/stomp_base/dashboard`
- Console: `/stomp_base/console`
- Settings: `/stomp_base/settings`

You can also change the language through the web interface by accessing the Settings page.

## Development

To contribute to Stomp Base, clone the repository and run the following commands:

```bash
bundle install

This project separates tests into two categories for optimal performance and clarity:

Tests for core StompBase logic that doesn't require Rails or UI components:

• Configuration tests (spec/unit/configuration_spec.rb)
• Core module tests (spec/lib/)
• Helper methods
• Business logic

These tests use only spec_helper.rb and don't require heavy Rails dependencies.

Run logic tests:

bundle exec rspec spec/lib/ spec/unit/

Tests for Rails-specific features like:

• ViewComponents
• Controllers
• Integration tests

These tests run within the rails_demo application environment and have access to all Rails features.

Run Rails/UI tests:

cd spec/rails_demo
bundle install
bundle exec rspec spec/

Important: The main spec/rails_helper.rb is now deprecated. Use the appropriate helper based on your test type:

• For pure Ruby logic tests: Use spec_helper.rb
• For Rails-based tests: Use spec/rails_demo/spec/rails_helper.rb

The deprecated spec/rails_helper.rb will show warnings and automatically redirect to the appropriate helper file.

This separation allows:

1. Faster pure logic tests - No need to boot Rails or load heavy dependencies
2. Isolated dependencies - Main gem doesn't need to include Rails development dependencies
3. Clear separation of concerns - Business logic vs UI/Rails logic

• ComponentTests moved from spec/components/ to spec/rails_demo/spec/components/
• Controller tests moved from spec/controllers/ to spec/rails_demo/spec/controllers/
• Pure Ruby tests remain in spec/lib/

Run all tests:

rspec

StompBase.configure do |config|
  config.locale = :ja                    # Set interface language
  config.available_locales = [:en, :ja]  # Available language options (read-only)
  
  # Console configuration
  config.allow_console_in_production = false # Allow console functionality in production (default: false)
  
  # Authentication options
  config.enable_authentication(          # Enable authentication
    method: :basic_auth,                 # :basic_auth, :api_key, or :custom
    username: 'admin',                   # For basic_auth
    password: 'password',                # For basic_auth
    keys: ['api-key'],                   # For api_key (array of valid keys)
    authenticator: -> { }                # For custom (callable object)
  )
  config.disable_authentication          # Disable authentication
end

# Check if authentication is enabled
StompBase.authentication_enabled?    # => true or false

# Enable authentication
StompBase.enable_authentication(method: :basic_auth, username: 'admin', password: 'pass')

# Disable authentication
StompBase.disable_authentication

For security reasons, the Rails console functionality is disabled in production environments by default. You can enable it if needed:

# config/initializers/stomp_base.rb
StompBase.configure do |config|
  # Enable console functionality in production (disabled by default for security)
  config.allow_console_in_production = true
end

⚠️ Security Warning: Enabling console functionality in production environments poses significant security risks. Only enable this feature if you fully understand the implications and have proper security measures in place.

# Get current locale
StompBase.locale         # => :en

# Set locale directly
StompBase.locale = :ja   # Set to Japanese
StompBase.locale = :en   # Set to English (default)

When included in controllers or views:

include StompBase::I18nHelper

# Translate keys with automatic "stomp_base." prefix
t('dashboard.title')        # => "Stomp Base Dashboard" or "Stomp Base ダッシュボード"
t('console.placeholder')    # => "Enter Ruby code..." or "Ruby コードを入力してください..."

# Get available locales
available_locales          # => [:en, :ja]

# Get current locale
current_locale            # => :en or :ja

# Get locale display name
locale_name(:en)          # => "English"
locale_name(:ja)          # => "日本語"

The engine automatically saves the selected language to the user's session:

# Language preference is stored in session[:stomp_base_locale]
# and persists across page reloads and browser sessions

Translation files are located in config/locales/:

• en.yml - English translations
• ja.yml - Japanese translations

You can add more languages by creating additional YAML files and updating the configuration.

StompBase has built-in authentication features that can be easily enabled through configuration files without using database or session functionality.

The most basic authentication method. Set a username and password.

# config/initializers/stomp_base.rb
StompBase.configure do |config|
  config.locale = :ja
  
  # Enable Basic Authentication
  config.enable_authentication(
    method: :basic_auth,
    username: 'admin',
    password: 'secret123'
  )
end

API key-based authentication. Multiple keys can be configured.

# config/initializers/stomp_base.rb
StompBase.configure do |config|
  config.locale = :ja
  
  # Enable API Key Authentication
  config.enable_authentication(
    method: :api_key,
    keys: ['your-api-key-1', 'your-api-key-2']
  )
end

API keys can be sent in the following ways:

• HTTP Header: X-API-Key: your-api-key
• URL Parameter: ?api_key=your-api-key

You can implement your own custom authentication logic.

# config/initializers/stomp_base.rb
StompBase.configure do |config|
  config.locale = :ja
  
  # Enable Custom Authentication
  config.enable_authentication(
    method: :custom,
    authenticator: ->(request, params) {
      # Implement your custom authentication logic
      # Return true for authentication success, false for failure
      token = request.headers['Authorization']
      token == 'Bearer your-custom-token'
    }
  )
end

To disable authentication:

# config/initializers/stomp_base.rb
StompBase.configure do |config|
  config.disable_authentication
end

# Or simply
StompBase.disable_authentication

To skip authentication for specific controllers or actions:

class MyController < StompBase::ApplicationController
  skip_before_action :authenticate_stomp_base, only: [:public_action]
  
  def public_action
    # Accessible without authentication
  end
  
  def private_action
    # Requires authentication
  end
end

Example of using different settings for production and development environments:

# config/initializers/stomp_base.rb
StompBase.configure do |config|
  config.locale = :ja
  
  if Rails.env.production?
    # Strong authentication for production
    config.enable_authentication(
      method: :api_key,
      keys: [ENV['STOMP_BASE_API_KEY']]
    )
    # Console disabled in production by default for security
    # config.allow_console_in_production = true  # Uncomment only if absolutely necessary
  elsif Rails.env.development?
    # Simple authentication for development
    config.enable_authentication(
      method: :basic_auth,
      username: 'dev',
      password: 'dev'
    )
    # Console enabled in development by default
  else
    # Disable authentication for test environment
    config.disable_authentication
  end
end

• It is recommended to manage Basic Auth passwords and API keys using environment variables
• Use HTTPS (especially when using Basic Authentication)
• Update API keys regularly
• Be careful not to output authentication information to log files
• Console functionality should remain disabled in production environments unless absolutely necessary for debugging
• If console access is required in production, ensure strong authentication is enabled and access is properly logged

The authentication feature is implemented with the following approach:

1. Simple Authentication

   • Basic Authentication (username/password)
   • API Key Authentication (header or parameter)
   • Custom Authentication (custom logic)

2. Configuration via initializer file

   # config/initializers/stomp_base.rb
   StompBase.configure do |config|
     config.enable_authentication(
       method: :basic_auth,
       username: 'admin',
       password: 'password'
     )
   end

3. No database or session functionality

   • Memory-based configuration management
   • Authentication information via HTTP headers or parameters
   • Simple implementation without persistence

• lib/stomp_base/authentication.rb - Authentication feature implementation
• lib/stomp_base/configuration.rb - Added authentication configuration functionality
• spec/unit/configuration_spec.rb - Unit tests for configuration class

• lib/stomp_base.rb - Authentication feature loading and helper method additions
• app/controllers/stomp_base/application_controller.rb - Authentication module integration
• stomp_base.gemspec - Added authentication feature description
• Gemfile - Added bigdecimal dependency

1. Access without authentication: Correctly rejected with 401 Unauthorized
2. Correct authentication credentials: Successfully accessed with 200 OK
3. Incorrect authentication credentials: Correctly rejected with 401 Unauthorized
4. Demo application: Working normally at localhost:3001

Authentication feature implementation is complete. The following extensions are possible if needed:

• Add authentication logging
• Rate limiting functionality
• Dynamic authentication configuration changes
• Addition of more authentication methods

We welcome contributions to Stomp Base! Here's how you can help:

1. Fork the repository on GitHub
2. Clone your fork locally:

   git clone https://github.com/YOUR_USERNAME/stomp_base.git
   cd stomp_base

3. Install dependencies:

   bundle install

4. Create a feature branch:

   git checkout -b feature/your-feature-name

1. Run the test suite to ensure everything works:

   rspec

2. Start the demo application for testing:

   cd spec/rails_demo
   bundle install
   rails server -p 3001

   Visit http://localhost:3001/stomp_base to see your changes.

3. Run Lookbook for component development:

   rails server
   # Visit http://localhost:3001/rails/lookbook

1. Write tests for your changes in the spec/ directory
2. Follow Ruby style guidelines and ensure your code is properly formatted
3. Add or update documentation as needed
4. Test your changes thoroughly:

   rspec

• 🐛 Bug fixes: Fix issues or unexpected behavior
• ✨ New features: Add new functionality to the engine
• 📚 Documentation: Improve or add documentation
• 🎨 UI/UX improvements: Enhance the user interface
• 🌐 Translations: Add support for new languages
• 🧪 Tests: Improve test coverage
• 🔧 Refactoring: Improve code quality without changing functionality

1. Commit your changes with clear, descriptive messages:

   git add .
   git commit -m "Add: Brief description of your changes"

2. Push to your fork:

   git push origin feature/your-feature-name

3. Create a Pull Request on GitHub with:

   • Clear title and description
   • Reference to any related issues
   • Screenshots for UI changes
   • Test results confirmation

• Keep PRs focused: One feature or fix per PR
• Write clear descriptions: Explain what changes you made and why
• Include tests: All new code should have appropriate tests
• Update documentation: Update README or other docs if needed
• Follow existing patterns: Match the existing code style and architecture

• Follow Ruby community standards
• Use meaningful variable and method names
• Add comments for complex logic
• Keep methods small and focused
• Use ViewComponent patterns for new UI components

• Write RSpec tests for new functionality
• Ensure all tests pass before submitting
• Include both unit and integration tests where appropriate
• Test edge cases and error conditions

Found a bug or have a suggestion? Please:

1. Check existing issues to avoid duplicates
2. Create a new issue with:
   • Clear, descriptive title
   • Steps to reproduce (for bugs)
   • Expected vs actual behavior
   • Ruby/Rails version information
   • Any relevant error messages

• GitHub Issues: For bug reports and feature requests
• GitHub Discussions: For questions and general discussion
• Pull Requests: For code contributions

Contributors will be acknowledged in:

• GitHub contributors list
• Release notes for significant contributions
• This README (if you make substantial contributions)

Thank you for helping make Stomp Base better! 🙏

This project is licensed under the MIT License. See the LICENSE file for details.