feat: Implement robust Couchbase error handling and modernize test infrastructure (#8)

* feat: Enhance Couchbase initialization and add hotel API endpoints

- Improved Couchbase initialization with error handling for misconfigurations.
- Added new API endpoints for hotel autocomplete and filtering in Swagger documentation.
- Updated Swagger server URL to a more generic format.

* fix: Address valid Gemini Code Assist feedback

Fixes 4 valid issues identified in PR #8 code review:

1. HIGH PRIORITY - Fixed constant re-assignment in couchbase.rb
   - Changed DB_USERNAME, DB_PASSWORD, DB_CONN_STR to local variables
   - Eliminates Ruby "already initialized constant" warnings
   - Constants at top of file remain for CI environment
   - Local variables used only in dev environment

2. Fixed rswag spec grammar (line 5)
   - Changed "Retrieve suggestion" → "Retrieve suggestions"
   - Matches plural array return type

3. Fixed misleading response description (line 22)
   - Changed "No suggestion" → "List of hotel name suggestions"
   - 200 status should describe success case, not edge case

4. Fixed incorrect response descriptions (lines 73 & 93)
   - Changed "only one Hotels found" → "List of hotels matching the filter criteria"
   - Fixed grammar and made description generic for filter endpoint

Note: Rejected Gemini's metaprogramming suggestion for search index
assignment as it adds unnecessary complexity without benefit.

Regenerated swagger.yaml from updated rswag specs.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* feat: Add workflow_dispatch trigger for manual CI runs

Allows developers to manually trigger the CI workflow from the
GitHub Actions UI.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* refactor: Fix Couchbase integration test failures and improve error handling

This commit addresses the failing integration tests and implements a robust
error handling strategy for Couchbase connections.

## Problem Fixed
- 25 out of 27 integration tests were failing with "NoMethodError: undefined
  method 'get' for nil"
- Couchbase collection constants (AIRLINE_COLLECTION, AIRPORT_COLLECTION,
  ROUTE_COLLECTION) were nil due to silent initialization failures

## Changes Made

### Core Fixes
- Created CouchbaseConnection concern for centralized connection checking
- Updated all models (Airline, Airport, Route, Hotel) to use ensure_couchbase!
- Changed ApplicationController to inherit from ActionController::API
- Improved Couchbase initializer with environment-specific error handling and
  retry logic for transient failures
- Removed skip_before_action :verify_authenticity_token from all API controllers
  (not needed for ActionController::API)

### Code Organization
- Renamed HotelSearch model to Hotel for consistency with other models
- Reorganized test files following RSpec conventions:
  * spec/requests/swagger/ - Swagger/rswag documentation specs
  * spec/requests/api/v1/ - Integration test specs
  * Removed test/integration/ directory

### New Features
- Added health check endpoint (GET /api/v1/health) for monitoring Couchbase
  connectivity
- Added retry logic for CI to handle transient network failures
- Added comprehensive troubleshooting documentation in README.md

### CI/CD Improvements
- Updated CI workflow to validate Couchbase configuration before running tests
- Added connection test step to verify database availability
- Updated test paths to use spec/requests instead of test/integration

## Test Results
- All 27 integration tests now pass (0 failures)
- Swagger documentation regenerated successfully (64 examples)
- Health endpoint verified working

## Files Modified
- Models: airline.rb, airport.rb, route.rb, hotel.rb (renamed from hotel_search.rb)
- Controllers: airlines, airports, routes, hotels, health (new), application
- Config: couchbase.rb initializer, routes.rb, ci.yml
- Tests: Reorganized from test/integration/ to spec/requests/api/v1/
- Docs: README.md with troubleshooting guide

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* refactor: Convert swagger specs to documentation-only

Simplified swagger specs to focus on API documentation generation
rather than duplicating integration testing. This change improves
maintainability and test execution speed.

Changes:
- Converted all swagger specs (airlines, airports, routes, hotels) to
  documentation-only mode
- Removed database setup/teardown logic from swagger specs
- Added inline comments indicating actual testing is in
  spec/requests/api/v1/
- Updated CI workflow to:
  - Run only integration tests from spec/requests/api/v1/
  - Verify swagger documentation generates without errors
  - Skip redundant swagger spec testing
- Regenerated swagger.yaml with simplified specs

Benefits:
- Faster swagger documentation generation (64 examples, 0 failures)
- Clear separation of concerns: swagger for docs, integration tests
  for testing
- Reduced CI execution time
- Eliminated complex test data management in swagger specs
- Integration tests in spec/requests/api/v1/ provide actual API
  validation

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

---------

Co-authored-by: Claude <[email protected]>

Author: teetangh

.github/workflows/ci.yml

@@ -7,6 +7,7 @@ on:
     branches: [main]
   schedule:
     - cron: "40 9 * * *"
+  workflow_dispatch:
 
 jobs:
   run_tests:
@@ -27,8 +28,64 @@ jobs:
           ruby-version: 3.4.1
           bundler-cache: true
 
-      - name: Run tests
-        run: bundle exec rspec test/integration
+      - name: Validate Couchbase Configuration
+        run: |
+          echo "Validating Couchbase environment variables..."
+
+          if [ -z "$DB_CONN_STR" ]; then
+            echo "::error::DB_CONN_STR environment variable is not set"
+            exit 1
+          fi
+
+          if [ -z "$DB_USERNAME" ]; then
+            echo "::error::DB_USERNAME environment variable is not set"
+            exit 1
+          fi
+
+          if [ -z "$DB_PASSWORD" ]; then
+            echo "::error::DB_PASSWORD secret is not set"
+            exit 1
+          fi
+
+          echo "✓ All Couchbase environment variables are configured"
+        env:
+          DB_CONN_STR: ${{ vars.DB_CONN_STR }}
+          DB_USERNAME: ${{ vars.DB_USERNAME }}
+          DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
+
+      - name: Test Couchbase Connection
+        run: |
+          bundle exec rails runner '
+            begin
+              if defined?(COUCHBASE_CLUSTER) && COUCHBASE_CLUSTER
+                bucket = COUCHBASE_CLUSTER.bucket("travel-sample")
+                puts "✓ Successfully connected to Couchbase cluster"
+                puts "✓ Successfully accessed travel-sample bucket"
+              else
+                puts "✗ Couchbase cluster not initialized"
+                exit 1
+              end
+            rescue => e
+              puts "✗ Failed to connect to Couchbase: #{e.class.name} - #{e.message}"
+              exit 1
+            end
+          '
+        env:
+          DB_CONN_STR: ${{ vars.DB_CONN_STR }}
+          DB_USERNAME: ${{ vars.DB_USERNAME }}
+          DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
+          CI: true
+
+      - name: Run integration tests
+        run: bundle exec rspec spec/requests/api/v1
+
+      - name: Verify Swagger documentation generates
+        run: bundle exec rake rswag:specs:swaggerize
+        env:
+          DB_CONN_STR: ${{ vars.DB_CONN_STR }}
+          DB_USERNAME: ${{ vars.DB_USERNAME }}
+          DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
+          CI: true
 
       - name: Report Status
         if: always()

README.md

@@ -120,9 +120,121 @@ DB_PASSWORD=<password_for_user>
 ### Run the integration tests
 
 ```sh
-bundle exec rspec test/integration
+bundle exec rspec spec/requests
 ```
 
+## Troubleshooting
+
+### Integration Tests Failing with "undefined method 'get' for nil"
+
+This error means Couchbase is not properly initialized. Follow these steps:
+
+#### 1. Verify Environment Variables
+
+For local development, ensure `dev.env` file exists in project root:
+
+```bash
+cat dev.env
+```
+
+Should contain:
+```
+DB_CONN_STR="couchbases://cb.hlcup4o4jmjr55yf.cloud.couchbase.com"
+DB_USERNAME="your-username"
+DB_PASSWORD="your-password"
+```
+
+#### 2. Verify Couchbase Connection
+
+Test the connection:
+```bash
+bundle exec rails runner 'puts COUCHBASE_CLUSTER ? "✓ Connected" : "✗ Not connected"'
+```
+
+#### 3. Verify travel-sample Bucket
+
+The application requires the `travel-sample` bucket with:
+- **Scope:** `inventory`
+- **Collections:** `airline`, `airport`, `route`, `hotel`
+
+For Couchbase Capella:
+1. Log into Capella console
+2. Navigate to your cluster
+3. Check Buckets > travel-sample exists
+4. Verify inventory scope and collections exist
+
+#### 4. Check Permissions
+
+The database user needs:
+- Read/Write access to `travel-sample` bucket
+- Query permissions for N1QL queries
+- Search permissions for FTS operations
+
+#### 5. Verify Network Access (Capella Only)
+
+For Couchbase Capella:
+1. Go to Settings > Allowed IP Addresses
+2. Add your IP address or `0.0.0.0/0` for testing
+3. Ensure cluster is not paused
+
+### CI Tests Failing
+
+Check GitHub repository configuration:
+
+1. **Secrets** (Settings > Secrets and variables > Actions > Secrets):
+   - `DB_PASSWORD` - Your Couchbase password
+
+2. **Variables** (Settings > Secrets and variables > Actions > Variables):
+   - `DB_CONN_STR` - Your Couchbase connection string
+   - `DB_USERNAME` - Your Couchbase username
+
+3. **Capella IP Allowlist**:
+   - GitHub Actions runners use dynamic IPs
+   - Temporarily allow `0.0.0.0/0` or use Capella's "Allow All IPs" option
+
+### Common Errors
+
+**Error:** `Couchbase::Error::AuthenticationFailure`
+- **Solution:** Check username/password in `dev.env` or GitHub Secrets
+
+**Error:** `Couchbase::Error::BucketNotFound`
+- **Solution:** Ensure `travel-sample` bucket is created and loaded
+
+**Error:** `Couchbase::Error::Timeout`
+- **Solution:** Check network connectivity, verify connection string uses correct protocol (`couchbase://` for local, `couchbases://` for Capella)
+
+**Error:** `Couchbase::Error::ScopeNotFound` or `CollectionNotFound`
+- **Solution:** The initializer auto-creates scope/collections, but user needs create permissions
+
+### Health Check Endpoint
+
+Check application health:
+```bash
+curl http://localhost:3000/api/v1/health
+```
+
+Response shows Couchbase status:
+```json
+{
+  "status": "healthy",
+  "timestamp": "2025-12-02T10:30:00Z",
+  "services": {
+    "couchbase": {
+      "status": "up",
+      "message": "Connected to travel-sample bucket"
+    }
+  }
+}
+```
+
+### Getting Help
+
+If issues persist:
+1. Check application logs for detailed error messages
+2. Verify Ruby version matches `.ruby-version` (3.4.1)
+3. Run `bundle install` to ensure all gems are current
+4. Check Couchbase SDK compatibility
+
 # Appendix
 
 ## Data Model

app/controllers/api/v1/airlines_controller.rb

@@ -3,7 +3,6 @@
 module Api
   module V1
     class AirlinesController < ApplicationController
-      skip_before_action :verify_authenticity_token, only: %i[create update destroy]
       before_action :set_airline, only: %i[show update destroy]
 
       # GET /api/v1/airlines/{id}

app/controllers/api/v1/airports_controller.rb

@@ -3,7 +3,6 @@
 module Api
   module V1
     class AirportsController < ApplicationController
-      skip_before_action :verify_authenticity_token, only: %i[create update destroy]
       before_action :set_airport, only: %i[show update destroy]
 
       # GET /api/v1/airports/{id}

app/controllers/api/v1/health_controller.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Api
+  module V1
+    class HealthController < ApplicationController
+      def show
+        health_status = {
+          status: 'healthy',
+          timestamp: Time.current.iso8601,
+          services: {
+            couchbase: check_couchbase
+          }
+        }
+
+        all_up = health_status[:services].values.all? { |s| s[:status] == 'up' }
+        status_code = all_up ? :ok : :service_unavailable
+
+        render json: health_status, status: status_code
+      end
+
+      private
+
+      def check_couchbase
+        if defined?(COUCHBASE_CLUSTER) && COUCHBASE_CLUSTER
+          # Perform simple bucket check to verify connection
+          COUCHBASE_CLUSTER.bucket('travel-sample')
+          { status: 'up', message: 'Connected to travel-sample bucket' }
+        else
+          { status: 'down', message: 'Couchbase not initialized' }
+        end
+      rescue StandardError => e
+        { status: 'down', message: e.message }
+      end
+    end
+  end
+end

app/controllers/api/v1/hotels_controller.rb

@@ -3,34 +3,33 @@
 module Api
     module V1
         class HotelsController < ApplicationController
-            skip_before_action :verify_authenticity_token, only: %i[search filter]
             before_action :validate_query_params, only: [:search]
             # GET /api/v1/hotels/autocomplete
             def search
-                @hotels = HotelSearch.search_name(params[:name])
+                @hotels = Hotel.search_name(params[:name])
                 render json: @hotels, status: :ok
             rescue StandardError => e
                 render json: { error: 'Internal server error', message: e.message }, status: :internal_server_error
             end
 
             # GET /api/v1/hotels/filter
             def filter
-                @hotels = HotelSearch.filter(HotelSearch.new(
+                @hotels = Hotel.filter(Hotel.new(
                   {
-                    "name"=> hotel_search_params[:name],
-                    "title" => hotel_search_params[:title],
-                    "description" => hotel_search_params[:description],
-                    "country" => hotel_search_params[:country],
-                    "city" => hotel_search_params[:city],
-                    "state" => hotel_search_params[:state]
+                    "name"=> hotel_params[:name],
+                    "title" => hotel_params[:title],
+                    "description" => hotel_params[:description],
+                    "country" => hotel_params[:country],
+                    "city" => hotel_params[:city],
+                    "state" => hotel_params[:state]
                   }
-                ), hotel_search_params[:offset],  hotel_search_params[:limit])
+                ), hotel_params[:offset],  hotel_params[:limit])
                 render json: @hotels, status: :ok
             rescue StandardError => e
                 render json: { error: 'Internal server error', message: e.message }, status: :internal_server_error
             end
 
-            def hotel_search_params
+            def hotel_params
                 params.require(:hotel).permit(:name, :title, :description, :country, :city, :state, :offset, :limit)
             end
 

app/controllers/api/v1/routes_controller.rb

@@ -3,7 +3,6 @@
 module Api
   module V1
     class RoutesController < ApplicationController
-      skip_before_action :verify_authenticity_token, only: %i[create update destroy]
       before_action :set_route, only: %i[show update destroy]
 
       # GET /api/v1/routes/{id}

app/controllers/application_controller.rb

@@ -1,2 +1,12 @@
-class ApplicationController < ActionController::Base
+class ApplicationController < ActionController::API
+  rescue_from CouchbaseConnection::CouchbaseUnavailableError, with: :handle_database_unavailable
+
+  private
+
+  def handle_database_unavailable(exception)
+    render json: {
+      error: 'Service Unavailable',
+      message: 'Database connection is not available. Please check configuration or try again later.'
+    }, status: :service_unavailable
+  end
 end

app/models/airline.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 class Airline
+  include CouchbaseConnection
+
   attr_accessor :name, :iata, :icao, :callsign, :country
 
   def initialize(attributes)
@@ -12,13 +14,15 @@ def initialize(attributes)
   end
 
   def self.find(id)
+    ensure_couchbase!
     result = AIRLINE_COLLECTION.get(id)
     new(result.content) if result.success?
   rescue Couchbase::Error::DocumentNotFound
     nil
   end
 
   def self.all(country = nil, limit = 10, offset = 0)
+    ensure_couchbase!
     bucket_name = 'travel-sample'
     scope_name = 'inventory'
     collection_name = 'airline'
@@ -33,6 +37,7 @@ def self.all(country = nil, limit = 10, offset = 0)
   end
 
   def self.to_airport(destination_airport_code, limit = 10, offset = 0)
+    ensure_couchbase!
     bucket_name = 'travel-sample'
     scope_name = 'inventory'
     route_collection_name = 'route'
@@ -58,6 +63,7 @@ def self.to_airport(destination_airport_code, limit = 10, offset = 0)
   end
 
   def self.create(id, attributes)
+    ensure_couchbase!
     required_fields = %w[name iata icao callsign country]
     missing_fields = required_fields - attributes.keys
     extra_fields = attributes.keys - required_fields
@@ -78,6 +84,7 @@ def self.create(id, attributes)
   end
 
   def update(id, attributes)
+    self.class.ensure_couchbase!
     required_fields = %w[name iata icao callsign country]
     missing_fields = required_fields - attributes.keys
     extra_fields = attributes.keys - required_fields
@@ -98,6 +105,7 @@ def update(id, attributes)
   end
 
   def destroy(id)
+    self.class.ensure_couchbase!
     AIRLINE_COLLECTION.remove(id)
   end
 end