open_rosa 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4971029b8b1f9034f894d18db290b204f7e4a8a62d7955dd9ecc9bf23a2669fc
+  data.tar.gz: 3dc882cc5e3b522d920c69c0b18d82fb6c8d4a2b0e44ecd41fc18155487f1efc
+SHA512:
+  metadata.gz: b90bcba3f90852d450de4569d26a3e3ffff4b4e67e7a879ad4115f638ee3871033d3f92e0dd18ad810b33255b54e9ab8f4142c34e24a75c5dfcb42dd6dfc3dc3
+  data.tar.gz: bb75af6367be14823f22259ddaff589f48b6a3f33794c0874633182741080cd2502d02bb87242520f71ca3486a7e8ddf28b8aa11f12c811ee706c32d454c76b6

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-12-26
+
+Initial release.
+
+### Added
+
+- Form DSL for defining OpenRosa forms with metadata (`form_id`, `version`, `name`, `description_text`, `download_url`, `manifest_url`)
+- Field types: `input`, `select1`, `select`, `boolean`, `range`, `upload`, `trigger`, `group`, `repeat`
+- XForm XML generation from form definitions
+- Form List API for listing available forms
+- Manifest support for media files
+- Submission parsing with support for XML data and file attachments
+- Rack middleware for serving OpenRosa endpoints (`/formList`, `/forms/:id`, `/submission`)
+- Per-form and global submission handlers
+- Authentication hook support
+- Ruby 3.2+ compatibility

data/CLAUDE.md

@@ -0,0 +1 @@
+Before finishing a task, run `rake` to make sure that tests and Rubocop is happy. Fix as many Rubocop issues as you can. If you can't, use the comment syntax to disable the rule.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Alex Watt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,285 @@
+# OpenRosa Ruby
+
+A Ruby gem for building [OpenRosa](https://docs.getodk.org/openrosa/) compliant form servers. Define forms with a clean DSL, serve them via Rack middleware, and handle submissions from mobile data collection apps like ODK Collect.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "open_rosa"
+```
+
+Or install directly:
+
+```bash
+gem install open_rosa
+```
+
+## Quick Start
+
+### 1. Define a Form
+
+```ruby
+class SurveyForm < OpenRosa::Form
+  form_id "my_survey"
+  version "1.0.0"
+  name "Customer Survey"
+
+  input :name, label: "Your Name", type: :string, required: true
+  input :email, label: "Email", type: :string
+  input :age, label: "Age", type: :int
+
+  select1 :satisfaction,
+          label: "How satisfied are you?",
+          choices: {
+            "very_satisfied" => "Very Satisfied",
+            "satisfied" => "Satisfied",
+            "neutral" => "Neutral",
+            "dissatisfied" => "Dissatisfied"
+          },
+          required: true
+
+  boolean :would_recommend, label: "Would you recommend us?"
+
+  input :comments, label: "Additional Comments", type: :string
+end
+```
+
+### 2. Mount the Middleware
+
+```ruby
+# config.ru (Rack) or config/application.rb (Rails)
+use OpenRosa::Middleware do |config|
+  config.base_url = "https://example.com"
+  config.mount_path = "/openrosa"
+  config.forms = [SurveyForm]
+
+  config.on_submission do |submission|
+    puts "Received: #{submission.form_id}"
+    puts "Data: #{submission.data}"
+    "Thank you for your submission!"
+  end
+end
+```
+
+### 3. Available Endpoints
+
+The middleware provides these OpenRosa-compliant endpoints:
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/openrosa/formList` | List available forms |
+| GET | `/openrosa/forms/:id` | Download form XForm XML |
+| HEAD | `/openrosa/submission` | Pre-flight check |
+| POST | `/openrosa/submission` | Submit form data |
+
+## Field Types
+
+### input
+
+Text, numeric, and date inputs:
+
+```ruby
+input :name, label: "Name", type: :string, required: true
+input :age, label: "Age", type: :int
+input :temperature, label: "Temperature", type: :decimal
+input :birthdate, label: "Birth Date", type: :date
+input :appointment, label: "Appointment", type: :dateTime
+input :start_time, label: "Start Time", type: :time
+```
+
+### select1
+
+Single-choice selection:
+
+```ruby
+select1 :color,
+        label: "Favorite Color",
+        choices: { "r" => "Red", "g" => "Green", "b" => "Blue" },
+        appearance: "minimal"
+```
+
+### select
+
+Multiple-choice selection:
+
+```ruby
+select :topics,
+       label: "Topics of Interest",
+       choices: ["Technology", "Science", "Art", "Music"]
+```
+
+### boolean
+
+Yes/no questions:
+
+```ruby
+boolean :agree, label: "I agree to the terms", appearance: "checkbox"
+```
+
+### range
+
+Numeric range slider:
+
+```ruby
+range :rating,
+      label: "Rate 1-10",
+      start: 1,
+      end: 10,
+      step: 1,
+      type: :int
+```
+
+### upload
+
+File uploads:
+
+```ruby
+upload :photo, label: "Take a photo", mediatype: "image/*"
+upload :signature, label: "Signature", mediatype: "image/*", appearance: "signature"
+upload :audio, label: "Record audio", mediatype: "audio/*"
+```
+
+### trigger
+
+Action button (acknowledge/confirm):
+
+```ruby
+trigger :acknowledge, label: "I have read and understood", appearance: "acknowledge"
+```
+
+### group
+
+Logical grouping of fields:
+
+```ruby
+group :contact_info, label: "Contact Information" do
+  input :phone, label: "Phone", type: :string
+  input :address, label: "Address", type: :string
+end
+```
+
+### repeat
+
+Repeatable field groups:
+
+```ruby
+repeat :household_members, label: "Household Members" do
+  input :member_name, label: "Name", type: :string
+  input :member_age, label: "Age", type: :int
+end
+```
+
+## Form Metadata
+
+```ruby
+class MyForm < OpenRosa::Form
+  form_id "unique_form_id"           # Required: unique identifier
+  version "1.0.0"                    # Form version
+  name "Human Readable Name"         # Display name
+  description_text "Form description"
+  download_url "https://..."         # Optional: auto-generated from base_url if not set
+  manifest_url "https://..."         # URL for media manifest (if needed)
+end
+```
+
+## Handling Submissions
+
+### Global Handler (Middleware)
+
+```ruby
+use OpenRosa::Middleware do |config|
+  config.forms = [MyForm]
+
+  config.on_submission do |submission|
+    # submission.form_id      - Form identifier
+    # submission.instance_id  - Unique submission ID
+    # submission.data         - Hash of field values
+    # submission.metadata     - Submission metadata (timeStart, timeEnd, etc.)
+    # submission.raw_xml      - Original XML string
+    # submission.attachments  - Array of uploaded files
+
+    MyModel.create!(
+      form_id: submission.form_id,
+      data: submission.data
+    )
+
+    submission.attachments.each do |file|
+      # file.filename, file.content_type, file.read, file.size
+      save_file(file)
+    end
+
+    "Submission received!"  # Optional success message
+  end
+end
+```
+
+### Per-Form Handler
+
+```ruby
+class MyForm < OpenRosa::Form
+  form_id "my_form"
+
+  input :name, label: "Name", type: :string
+
+  on_submit do |submission|
+    # Handle submissions for this specific form
+    Record.create!(name: submission.data["name"])
+    "Thank you!"
+  end
+end
+```
+
+## Rails Integration
+
+```ruby
+# config/application.rb
+module MyApp
+  class Application < Rails::Application
+    config.middleware.use OpenRosa::Middleware do |config|
+      config.forms = [SurveyForm, FeedbackForm]
+      config.mount_path = "/openrosa"
+
+      config.on_submission do |submission|
+        FormSubmission.create!(
+          form_id: submission.form_id,
+          instance_id: submission.instance_id,
+          data: submission.data
+        )
+      end
+    end
+  end
+end
+```
+
+## Generating XForm XML
+
+You can generate the XForm XML directly:
+
+```ruby
+xml = SurveyForm.to_xml
+# => Complete XForm XML string
+
+hash = SurveyForm.form_hash
+# => "md5:abc123..." (for change detection)
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake` to run the tests and linter.
+
+```bash
+bin/setup
+rake
+```
+
+Use `bin/console` for an interactive prompt to experiment.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/alexcwatt/openrosa-ruby.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/examples/authentication.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# Authentication examples for OpenRosa middleware
+
+require "open_rosa"
+
+# rubocop:disable Metrics/MethodLength
+
+# Example 1: HTTP Basic Authentication (most common for ODK clients)
+class BasicAuthExample
+  def self.middleware
+    OpenRosa::Middleware.new do |config|
+      config.forms = [] # Add your forms here
+
+      config.authenticate do |env|
+        auth = Rack::Auth::Basic::Request.new(env)
+        if auth.provided? && auth.basic? && auth.credentials
+          username, password = auth.credentials
+          # Replace with your authentication logic:
+          # User.find_by(username: username)&.authenticate(password)
+          { username: username } if username == "admin" && password == "secret"
+        end
+      end
+
+      # Optional: Customize the realm shown in browser login prompt
+      config.authentication_realm = "ODK Collect"
+    end
+  end
+end
+
+# Example 2: Bearer Token Authentication (e.g. for API clients)
+class TokenAuthExample
+  def self.middleware
+    OpenRosa::Middleware.new do |config|
+      config.forms = [] # Add your forms here
+
+      config.authenticate do |env|
+        token = env["HTTP_AUTHORIZATION"]&.sub(/^Bearer /, "")
+        # Replace with your token validation:
+        # ApiKey.find_by(token: token, active: true)&.user
+        { token: token } if token == "valid-token-12345"
+      end
+    end
+  end
+end
+
+# Example 3: Selective Authentication (public formList, protected submissions)
+class SelectiveAuthExample
+  def self.middleware
+    OpenRosa::Middleware.new do |config|
+      config.forms = [] # Add your forms here
+
+      config.authenticate do |env|
+        auth = Rack::Auth::Basic::Request.new(env)
+        if auth.provided? && auth.basic? && auth.credentials
+          username, password = auth.credentials
+          username == "admin" && password == "secret"
+        end
+      end
+
+      # Skip auth for these paths (supports strings and regex)
+      config.skip_authentication_for = ["/formList", %r{/forms/}]
+    end
+  end
+end
+
+# Usage in config.ru:
+#   require_relative "examples/authentication"
+#   run BasicAuthExample.middleware
+#
+# In Rails (config/application.rb):
+#   config.middleware.use OpenRosa::Middleware do |config|
+#     config.authenticate do |env|
+#       # Your auth logic here
+#     end
+#   end
+#
+# The authenticated user is stored in env["openrosa.authenticated_user"]
+
+# rubocop:enable Metrics/MethodLength

data/examples/rack_app.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+# Example Rack application demonstrating OpenRosa middleware usage
+#
+# Run this with: rackup examples/rack_app.rb
+# Then access:
+#   - http://localhost:9292/openrosa/formList
+#   - http://localhost:9292/openrosa/forms/customer_survey
+
+require_relative "../lib/open_rosa"
+
+# Define a sample customer survey form
+class CustomerSurvey < OpenRosa::Form
+  form_id "customer_survey"
+  version "1.0.0"
+  name "Customer Satisfaction Survey"
+  description_text "Please rate your experience with our service"
+  download_url "http://localhost:9292/openrosa/forms/customer_survey"
+
+  # Customer information
+  input :customer_name,
+        label: "Your Name",
+        type: :string,
+        required: true
+
+  input :customer_email,
+        label: "Email Address",
+        type: :string
+
+  # Satisfaction rating
+  select1 :satisfaction,
+          label: "Overall Satisfaction",
+          choices: {
+            "very_satisfied" => "Very Satisfied",
+            "satisfied" => "Satisfied",
+            "neutral" => "Neutral",
+            "dissatisfied" => "Dissatisfied",
+            "very_dissatisfied" => "Very Dissatisfied"
+          },
+          required: true,
+          appearance: "minimal"
+
+  # Rating scale
+  range :service_rating,
+        label: "Rate our service (1-10)",
+        start: 1,
+        end: 10,
+        step: 1,
+        type: :int
+
+  # Comments
+  input :comments,
+        label: "Additional Comments",
+        type: :string
+
+  # Optional photo
+  upload :photo,
+         label: "Upload a photo (optional)",
+         mediatype: "image/*"
+
+  # Visit date
+  input :visit_date,
+        label: "Date of Visit",
+        type: :date
+
+  # Would recommend
+  boolean :would_recommend,
+          label: "Would you recommend us to a friend?",
+          appearance: "checkbox"
+end
+
+# Define an employee feedback form
+class EmployeeFeedback < OpenRosa::Form
+  form_id "employee_feedback"
+  version "2.0.0"
+  name "Employee Feedback Form"
+  description_text "Quarterly employee feedback survey"
+  download_url "http://localhost:9292/openrosa/forms/employee_feedback"
+
+  group :personal_info, label: "Personal Information" do
+    input :employee_id,
+          label: "Employee ID",
+          type: :string,
+          required: true
+
+    input :department,
+          label: "Department",
+          type: :string
+  end
+
+  group :feedback, label: "Feedback" do
+    select :areas_improvement,
+           label: "Areas for Improvement",
+           choices: [
+             "Communication",
+             "Work-Life Balance",
+             "Career Development",
+             "Management",
+             "Compensation"
+           ]
+
+    input :suggestions,
+          label: "Your Suggestions",
+          type: :string
+  end
+end
+
+# Create a simple Rack app that responds to non-OpenRosa paths
+app = lambda do |env|
+  request = Rack::Request.new(env)
+
+  if request.path == "/"
+    [
+      200,
+      { "Content-Type" => "text/html" },
+      [<<~HTML]
+        <!DOCTYPE html>
+        <html>
+          <head><title>OpenRosa Example Server</title></head>
+          <body>
+            <h1>OpenRosa Example Server</h1>
+            <h2>Available Endpoints:</h2>
+            <ul>
+              <li><a href="/openrosa/formList">GET /openrosa/formList</a> - List all forms</li>
+              <li><a href="/openrosa/formList?formID=customer_survey">GET /openrosa/formList?formID=customer_survey</a> - Filter by form ID</li>
+              <li><a href="/openrosa/formList?verbose=true">GET /openrosa/formList?verbose=true</a> - Verbose mode</li>
+              <li><a href="/openrosa/forms/customer_survey">GET /openrosa/forms/customer_survey</a> - Download Customer Survey form</li>
+              <li><a href="/openrosa/forms/employee_feedback">GET /openrosa/forms/employee_feedback</a> - Download Employee Feedback form</li>
+              <li>HEAD /openrosa/submission - Pre-flight check for submissions</li>
+              <li>POST /openrosa/submission - Submit form data (multipart/form-data)</li>
+            </ul>
+            <h2>Available Forms:</h2>
+            <ul>
+              <li><strong>customer_survey</strong> - Customer Satisfaction Survey (v1.0.0)</li>
+              <li><strong>employee_feedback</strong> - Employee Feedback Form (v2.0.0)</li>
+            </ul>
+          </body>
+        </html>
+      HTML
+    ]
+  else
+    [404, { "Content-Type" => "text/plain" }, ["Not Found"]]
+  end
+end
+
+# Wrap the app with OpenRosa middleware
+use OpenRosa::Middleware do |config|
+  config.forms = [CustomerSurvey, EmployeeFeedback]
+  config.mount_path = "/openrosa"
+
+  # Handle form submissions
+  config.on_submission do |submission|
+    # Print submission details to console
+    puts "\n=== Form Submission Received ==="
+    puts "Form ID: #{submission.form_id}"
+    puts "Instance ID: #{submission.instance_id}"
+    puts "Submitted at: #{submission.metadata[:timeEnd]}"
+    puts "Data:"
+    submission.data.each do |key, value|
+      puts "  #{key}: #{value}"
+    end
+
+    if submission.attachments.any?
+      puts "Attachments:"
+      submission.attachments.each do |att|
+        puts "  - #{att.filename} (#{att.content_type}, #{att.size} bytes)"
+        # In a real app, you'd save these files:
+        # File.write("uploads/#{att.filename}", att.read)
+      end
+    end
+    puts "================================\n"
+
+    # Return a custom success message
+    "Thank you! Your #{submission.form_id} submission has been received."
+  end
+end
+
+run app