open_rosa 0.1.0

data/lib/open_rosa/form_list.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module OpenRosa
+  # Generates OpenRosa Form List API XML responses
+  # Spec: https://docs.getodk.org/openrosa-form-list/
+  class FormList
+    XFORMS_LIST_NS = "http://openrosa.org/xforms/xformsList"
+
+    def initialize(forms, options = {})
+      @forms = forms
+      @verbose = options.fetch(:verbose, false)
+      @form_id = options[:form_id]
+      @base_url = options[:base_url]
+      @mount_path = options[:mount_path] || "/openrosa"
+    end
+
+    def to_xml
+      builder = Nokogiri::XML::Builder.new(encoding: "UTF-8") do |xml|
+        xml.xforms(xmlns: XFORMS_LIST_NS) do
+          filtered_forms.each do |form_class|
+            generate_xform_entry(xml, form_class)
+          end
+        end
+      end
+
+      builder.to_xml
+    end
+
+    private
+
+    def filtered_forms
+      return @forms unless @form_id
+
+      @forms.select { |form| form.form_id == @form_id }
+    end
+
+    def generate_xform_entry(xml, form_class)
+      xml.xform do
+        add_required_fields(xml, form_class)
+        add_verbose_fields(xml, form_class) if @verbose
+        add_optional_fields(xml, form_class)
+      end
+    end
+
+    def add_required_fields(xml, form_class)
+      xml.formID form_class.form_id
+      xml.name form_class.name if form_class.name
+      xml.version form_class.version if form_class.version
+      xml.hash_ form_class.form_hash
+      url = download_url_for(form_class)
+      xml.downloadUrl url if url
+    end
+
+    def download_url_for(form_class)
+      # Use explicit download_url if set on the form
+      return form_class.download_url if form_class.download_url
+
+      # Auto-generate from base_url if configured
+      unless @base_url
+        raise ArgumentError,
+              "Form '#{form_class.form_id}' has no download_url. " \
+              "Either set download_url on the form or configure base_url in the middleware."
+      end
+
+      "#{@base_url}#{@mount_path}/forms/#{form_class.form_id}"
+    end
+
+    def add_verbose_fields(xml, form_class)
+      xml.descriptionText form_class.description_text if form_class.description_text
+      xml.descriptionUrl form_class.description_url if form_class.description_url
+    end
+
+    def add_optional_fields(xml, form_class)
+      url = manifest_url_for(form_class)
+      xml.manifestUrl url if url
+    end
+
+    def manifest_url_for(form_class)
+      # Use explicit manifest_url if set on the form
+      return form_class.manifest_url if form_class.manifest_url
+
+      # Auto-generate from base_url if form has a manifest defined
+      return nil unless @base_url
+      return nil unless form_has_manifest?(form_class)
+
+      "#{@base_url}#{@mount_path}/manifests/#{form_class.form_id}"
+    end
+
+    def form_has_manifest?(form_class)
+      # Handle both class and instance (middleware passes instances)
+      klass = form_class.is_a?(Class) ? form_class : form_class.class
+      klass.respond_to?(:manifest) && klass.manifest
+    end
+  end
+end

data/lib/open_rosa/manifest.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module OpenRosa
+  # Represents a manifest of media files associated with a form.
+  # The manifest lists all supporting files (images, audio, video, entity lists)
+  # that need to be downloaded along with the form definition.
+  #
+  # @example Create a manifest with media files
+  #   manifest = OpenRosa::Manifest.new
+  #   manifest.add_media_file(
+  #     OpenRosa::MediaFile.new(
+  #       filename: "images/logo.png",
+  #       hash: "md5:abc123",
+  #       download_url: "https://example.com/media/logo.png"
+  #     )
+  #   )
+  #   xml = manifest.to_xml
+  #
+  # @example Create a manifest with entity list
+  #   manifest = OpenRosa::Manifest.new
+  #   manifest.add_media_file(
+  #     OpenRosa::MediaFile.new(
+  #       filename: "entities.csv",
+  #       hash: "md5:xyz789",
+  #       download_url: "https://example.com/entities.csv",
+  #       type: "entityList",
+  #       integrity_url: "https://example.com/entities/integrity"
+  #     )
+  #   )
+  class Manifest
+    attr_reader :media_files
+
+    # Creates a new Manifest
+    #
+    # @param media_files [Array<MediaFile>] Optional array of MediaFile objects
+    def initialize(media_files: [])
+      @media_files = media_files
+    end
+
+    # Adds a media file to the manifest
+    #
+    # @param media_file [MediaFile] The media file to add
+    # @return [Manifest] self for chaining
+    def add_media_file(media_file)
+      @media_files << media_file
+      self
+    end
+
+    # Generates OpenRosa manifest XML
+    #
+    # @return [String] XML string conforming to OpenRosa manifest spec
+    def to_xml
+      builder = Nokogiri::XML::Builder.new(encoding: "UTF-8") do |xml|
+        xml.manifest(xmlns: "http://openrosa.org/xforms/xformsManifest") do
+          media_files.each do |media_file|
+            build_media_file(xml, media_file)
+          end
+        end
+      end
+
+      builder.to_xml
+    end
+
+    # Check if the manifest is empty
+    #
+    # @return [Boolean] true if no media files
+    def empty?
+      media_files.empty?
+    end
+
+    # Count of media files in the manifest
+    #
+    # @return [Integer] number of media files
+    def count
+      media_files.count
+    end
+
+    private
+
+    def build_media_file(xml, media_file)
+      # Add type attribute only if specified
+      if media_file.type
+        xml.mediaFile(type: media_file.type) do
+          build_media_file_elements(xml, media_file)
+        end
+      else
+        xml.mediaFile do
+          build_media_file_elements(xml, media_file)
+        end
+      end
+    end
+
+    def build_media_file_elements(xml, media_file)
+      xml.filename media_file.filename
+      # Use text approach to avoid conflict with Object#hash
+      xml.text("\n    ")
+      xml.parent.add_child(Nokogiri::XML::Node.new("hash", xml.doc).tap { |n| n.content = media_file.hash })
+      xml.text("\n    ")
+      xml.downloadUrl media_file.download_url
+      xml.integrityUrl media_file.integrity_url if media_file.integrity_url
+    end
+  end
+end

data/lib/open_rosa/media_file.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module OpenRosa
+  # Represents a media file (image, audio, video, entity list) associated with a form.
+  # Media files are listed in the form's manifest and downloaded separately from the form definition.
+  #
+  # @example Create a media file with manual hash
+  #   media_file = OpenRosa::MediaFile.new(
+  #     filename: "images/logo.png",
+  #     hash: "md5:abc123def456",
+  #     download_url: "https://example.com/media/logo.png"
+  #   )
+  #
+  # @example Create a media file with automatic hash generation
+  #   media_file = OpenRosa::MediaFile.new(
+  #     filename: "images/logo.png",
+  #     file: "/path/to/logo.png",
+  #     download_url: "https://example.com/media/logo.png"
+  #   )
+  #
+  # @example Create an entity list media file
+  #   media_file = OpenRosa::MediaFile.new(
+  #     filename: "entities.csv",
+  #     hash: "md5:xyz789",
+  #     download_url: "https://example.com/entities.csv",
+  #     type: "entityList",
+  #     integrity_url: "https://example.com/entities/integrity"
+  #   )
+  class MediaFile
+    attr_reader :filename, :hash, :download_url, :type, :integrity_url
+
+    # Creates a new MediaFile
+    #
+    # @param filename [String] Unrooted file path (no drive letters, no absolute paths, no backslashes)
+    # @param hash [String, nil] MD5 hash in format "md5:..." (auto-generated if file provided)
+    # @param file [String, nil] Path to file for hash generation
+    # @param download_url [String] Full URI for downloading the file
+    # @param type [String, nil] Optional type (e.g., "entityList")
+    # @param integrity_url [String, nil] Required if type="entityList"
+    # @raise [ArgumentError] if filename is invalid, or if hash/file not provided, or entityList missing integrity_url
+    # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists
+    def initialize(filename:, download_url:, hash: nil, file: nil, type: nil, integrity_url: nil)
+      # rubocop:enable Metrics/ParameterLists
+      @filename = validate_filename(filename)
+      @download_url = download_url
+      @type = type
+      @integrity_url = integrity_url
+
+      # Hash can be provided or generated from file
+      if hash
+        @hash = hash
+      elsif file
+        @hash = generate_hash(file)
+      else
+        raise ArgumentError, "Either hash or file parameter must be provided"
+      end
+
+      # Validate entityList requirements
+      validate_entity_list if type == "entityList"
+    end
+    # rubocop:enable Metrics/MethodLength
+
+    private
+
+    def validate_filename(filename)
+      # Check for Windows drive letters (C:, D:, etc.)
+      raise ArgumentError, "Filename cannot contain a drive letter: #{filename}" if filename.match?(/^[A-Za-z]:/)
+
+      # Check for relative paths (..)
+      if filename.include?("..")
+        raise ArgumentError, "Filename cannot contain relative path components (..): #{filename}"
+      end
+
+      # Check for absolute paths (starting with /)
+      raise ArgumentError, "Filename cannot be an absolute path: #{filename}" if filename.start_with?("/")
+
+      # Check for backslashes (Windows-style paths)
+      raise ArgumentError, "Filename cannot contain backslash characters: #{filename}" if filename.include?("\\")
+
+      filename
+    end
+
+    def generate_hash(file_path)
+      content = File.read(file_path)
+      digest = Digest::MD5.hexdigest(content)
+      "md5:#{digest}"
+    end
+
+    def validate_entity_list
+      return if integrity_url
+
+      raise ArgumentError, "integrity_url is required when type is 'entityList'"
+    end
+  end
+end

data/lib/open_rosa/middleware.rb

@@ -0,0 +1,352 @@
+# frozen_string_literal: true
+
+require "rack"
+
+module OpenRosa
+  # Rack middleware for OpenRosa endpoints
+  #
+  # Provides endpoints for:
+  # - GET /formList - List available forms
+  # - GET /forms/:id - Download a specific form as XForm XML
+  # - POST /submission - Receive form submissions
+  # - HEAD /submission - Pre-flight check for submissions
+  #
+  # Example usage:
+  #   use OpenRosa::Middleware do |config|
+  #     config.forms = [MyForm, AnotherForm]
+  #     config.mount_path = "/openrosa"
+  #
+  #     # Handle submissions
+  #     config.on_submission do |submission|
+  #       # Save to database, process files, etc.
+  #       MySubmission.create!(
+  #         form_id: submission.form_id,
+  #         data: submission.data,
+  #         instance_id: submission.instance_id
+  #       )
+  #       "Thank you for your submission!"
+  #     end
+  #   end
+  class Middleware # rubocop:disable Metrics/ClassLength
+    OPENROSA_VERSION = "1.0"
+
+    attr_reader :app, :config
+
+    def initialize(app = nil, &block)
+      @app = app
+      @config = Configuration.new
+      block&.call(@config)
+    end
+
+    def call(env)
+      request = Rack::Request.new(env)
+
+      return delegate_to_app(env) unless handle_request?(request)
+
+      # Check authentication if configured
+      return unauthorized_response unless authenticated?(env, request)
+
+      route_request(request)
+    end
+
+    private
+
+    def delegate_to_app(env)
+      @app ? @app.call(env) : not_found_response
+    end
+
+    def handle_request?(request)
+      @app.nil? || openrosa_path?(request.path_info)
+    end
+
+    # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity
+    def route_request(request)
+      path = request.path_info
+      method = request.request_method
+
+      case [method, path]
+      when ["GET", "#{mount_path}/formList"]
+        handle_form_list(request)
+      when ["POST", "#{mount_path}/submission"]
+        handle_submission(request)
+      when ["HEAD", "#{mount_path}/submission"]
+        handle_submission_head(request)
+      else
+        # Check for form download pattern (GET /forms/:id)
+        if method == "GET" && (match = path.match(%r{^#{Regexp.escape(mount_path)}/forms/(.+)$}))
+          handle_form_download(request, match[1])
+        # Check for manifest download pattern (GET /manifests/:id)
+        elsif method == "GET" && (match = path.match(%r{^#{Regexp.escape(mount_path)}/manifests/(.+)$}))
+          handle_manifest(request, match[1])
+        else
+          delegate_to_app(request.env)
+        end
+      end
+    end
+    # rubocop:enable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity
+
+    def mount_path
+      @config.mount_path
+    end
+
+    def openrosa_path?(path)
+      path.start_with?(mount_path)
+    end
+
+    def handle_form_list(request)
+      form_list = FormList.new(available_forms, form_list_options(request))
+      openrosa_xml_response(form_list.to_xml)
+    end
+
+    def form_list_options(request)
+      {
+        form_id: request.params["formID"],
+        verbose: request.params["verbose"] == "true",
+        base_url: @config.base_url,
+        mount_path: mount_path
+      }
+    end
+
+    def handle_form_download(_request, form_id)
+      form = find_form(form_id)
+      return not_found_response unless form
+
+      xml = form.to_xml
+
+      openrosa_xml_response(xml)
+    end
+
+    def handle_manifest(_request, form_id)
+      form = find_form(form_id)
+      return not_found_response("Form not found") unless form
+
+      # Check if the form has a manifest method
+      return not_found_response("Manifest not found for this form") unless form.class.respond_to?(:manifest)
+
+      manifest = form.class.manifest
+      return not_found_response("Manifest not found for this form") if manifest.nil? || manifest.empty?
+
+      xml = manifest.to_xml
+
+      openrosa_xml_response(xml)
+    end
+
+    def available_forms
+      @config.forms.map do |form_class|
+        # If it's a class, instantiate it; otherwise use as-is
+        form_class.is_a?(Class) ? form_class.new : form_class
+      end
+    end
+
+    def find_form(form_id)
+      available_forms.find { |form| form.form_id == form_id }
+    end
+
+    def openrosa_xml_response(xml)
+      [
+        200,
+        {
+          "Content-Type" => "text/xml; charset=utf-8",
+          "X-OpenRosa-Version" => OPENROSA_VERSION,
+          "Date" => Time.now.httpdate
+        },
+        [xml]
+      ]
+    end
+
+    def handle_submission(request)
+      submission = parse_submission(request)
+      return submission if submission.is_a?(Array) # Error response
+
+      message = process_submission(submission)
+      return message if message.is_a?(Array) # Error response
+
+      openrosa_submission_response(message || "Submission received successfully")
+    end
+
+    def parse_submission(request)
+      Submission.parse(request)
+    rescue Submission::ParseError => e
+      error_response(400, "Invalid submission: #{e.message}")
+    end
+
+    def process_submission(submission)
+      form_class = find_form_class_for_submission(submission)
+      execute_submission_handler(form_class, submission)
+    rescue StandardError => e
+      error_response(500, "Server error: #{e.message}")
+    end
+
+    def find_form_class_for_submission(submission)
+      @config.forms.find do |fc|
+        form = fc.is_a?(Class) ? fc.new : fc
+        form.form_id == submission.form_id
+      end
+    end
+
+    def execute_submission_handler(form_class, submission)
+      # Try form-specific handler first
+      form_handler_result = form_class&.handle_submission(submission) if form_class
+
+      if form_handler_result
+        form_handler_result
+      elsif @config.submission_handler
+        @config.submission_handler.call(submission)
+      else
+        "Submission received successfully"
+      end
+    end
+
+    def handle_submission_head(_request)
+      # HEAD request for pre-flight check
+      # Return max content length we'll accept (10MB default)
+      max_size = @config.max_submission_size || 10_485_760
+
+      [
+        204,
+        {
+          "X-OpenRosa-Version" => OPENROSA_VERSION,
+          "X-OpenRosa-Accept-Content-Length" => max_size.to_s,
+          "Date" => Time.now.httpdate
+        },
+        []
+      ]
+    end
+
+    def openrosa_submission_response(message)
+      xml = build_openrosa_response_xml(message)
+
+      [
+        201,
+        {
+          "Content-Type" => "text/xml; charset=utf-8",
+          "X-OpenRosa-Version" => OPENROSA_VERSION,
+          "Date" => Time.now.httpdate
+        },
+        [xml]
+      ]
+    end
+
+    def build_openrosa_response_xml(message)
+      builder = Nokogiri::XML::Builder.new(encoding: "UTF-8") do |xml|
+        xml.OpenRosaResponse(xmlns: "http://openrosa.org/http/response") do
+          xml.message message
+        end
+      end
+
+      builder.to_xml
+    end
+
+    def error_response(status, message)
+      [
+        status,
+        {
+          "Content-Type" => "text/plain",
+          "X-OpenRosa-Version" => OPENROSA_VERSION,
+          "Date" => Time.now.httpdate
+        },
+        [message]
+      ]
+    end
+
+    def not_found_response(message = "Not Found")
+      [
+        404,
+        { "Content-Type" => "text/plain" },
+        [message]
+      ]
+    end
+
+    def authenticated?(env, request)
+      # No authentication handler configured = allow all requests
+      return true unless @config.authentication_handler
+
+      # Check if this path should skip authentication
+      return true if skip_authentication?(request.path_info)
+
+      # Call the authentication handler
+      result = @config.authentication_handler.call(env)
+
+      # Store the authenticated user/result in env for later use
+      env["openrosa.authenticated_user"] = result if result
+
+      # Return true if result is truthy (user object, true, etc.)
+      !!result
+    end
+
+    def skip_authentication?(path)
+      @config.skip_authentication_for.any? do |skip_path|
+        if skip_path.is_a?(Regexp)
+          path =~ skip_path
+        else
+          path == normalize_skip_path(skip_path)
+        end
+      end
+    end
+
+    def normalize_skip_path(path)
+      # Ensure skip path includes mount_path if it's a relative path
+      return path if path.start_with?(mount_path)
+
+      "#{mount_path}#{path}"
+    end
+
+    def unauthorized_response
+      [
+        401,
+        {
+          "Content-Type" => "text/plain",
+          "WWW-Authenticate" => "Basic realm=\"#{@config.authentication_realm}\"",
+          "X-OpenRosa-Version" => OPENROSA_VERSION,
+          "Date" => Time.now.httpdate
+        },
+        ["Unauthorized"]
+      ]
+    end
+
+    # Configuration object for the middleware
+    class Configuration
+      attr_accessor :forms, :mount_path, :base_url, :submission_handler, :max_submission_size,
+                    :authentication_handler, :skip_authentication_for, :authentication_realm
+
+      def initialize
+        @forms = []
+        @mount_path = "/openrosa"
+        @base_url = nil
+        @submission_handler = nil
+        @max_submission_size = 10_485_760 # 10MB default
+        @authentication_handler = nil
+        @skip_authentication_for = []
+        @authentication_realm = "OpenRosa"
+      end
+
+      # Set the submission handler callback
+      #
+      # @yield [submission] The parsed submission
+      # @yieldparam submission [Submission] The submission object
+      # @yieldreturn [String, nil] Optional success message
+      def on_submission(&block)
+        @submission_handler = block
+      end
+
+      # Set the authentication handler callback
+      #
+      # @yield [env] The Rack environment hash
+      # @yieldparam env [Hash] The Rack environment
+      # @yieldreturn [Object, true, false, nil] Return truthy to authenticate, falsy to deny
+      #
+      # Example:
+      #   config.authenticate do |env|
+      #     request = Rack::Request.new(env)
+      #     auth = Rack::Auth::Basic::Request.new(env)
+      #     if auth.provided? && auth.basic?
+      #       username, password = auth.credentials
+      #       User.authenticate(username, password) # Returns user object or nil
+      #     end
+      #   end
+      def authenticate(&block)
+        @authentication_handler = block
+      end
+    end
+  end
+end