CCAP-138: Added OneDrive transfer support. (#4)

* Added OpenAPI documentation.
* Updated class and module structure to be more accurate.
* Added document transfer endpoint with support for url sources and onedrive destinations.
* Added reusable response entities.
* Added additional documentation for the API.

Author: jamesiarmes

.github/config/rubocop_linter_action.yml

@@ -15,6 +15,7 @@ versions:
   - rubocop: 'latest'
   - rubocop-rake: 'latest'
   - rubocop-rspec: 'latest'
+  - rubocop-factory_bot: 'latest'
 
 # Description: RuboCop configuration file path relative to the workspace.
 # Valid options: A valid file path inside of the workspace.

.gitignore

@@ -1,6 +1,8 @@
 # Ignore local environment files
 .env
 *.env
+!sample.env
+coverage/
 
 # Ignore Byebug command history file.
 .byebug_history

.rspec

@@ -0,0 +1,4 @@
+--require spec_helper.rb
+--color
+--format RSpec::Github::Formatter
+--format documentation

.rubocop.yml

@@ -1,3 +1,24 @@
+require:
+  - rubocop-factory_bot
+  - rubocop-rake
+  - rubocop-rspec
+
 AllCops:
   NewCops: enable
   SuggestExtensions: true
+
+# Transient properties get mistaken for associations in FactoryBot.
+# See https://github.com/rubocop/rubocop-factory_bot/issues/73
+FactoryBot/FactoryAssociationWithStrategy:
+  Enabled: false
+
+# Count multi-line hashes and arrays in examples as one line.
+RSpec/ExampleLength:
+  CountAsOne:
+    - array
+    - hash
+
+Metrics/BlockLength:
+  AllowedMethods:
+    # Exclude grape `resource` blocks.
+    - resource

Gemfile

@@ -4,6 +4,10 @@ source 'https://rubygems.org'
 
 gemspec
 
+# TODO: Move to gemspec once a new release has been cut.
+# See https://github.com/kklimuk/microsoft-graph-client/pull/4
+gem 'microsoft-graph-client', git: 'https://github.com/jamesiarmes/microsoft-graph-client.git', branch: 'non-hash-body'
+
 group :development do
   gem 'rake', '~> 13.0'
   gem 'rubocop', '~> 1.48'

Gemfile.lock

@@ -1,16 +1,30 @@
+GIT
+  remote: https://github.com/jamesiarmes/microsoft-graph-client.git
+  revision: 206aa96ce1c4073b5c570accf1559af9c2e2e509
+  branch: non-hash-body
+  specs:
+    microsoft-graph-client (0.1.3)
+      httparty
+
 PATH
   remote: .
   specs:
     document-transfer-service (0.1.0)
+      adal (~> 1.0)
+      faraday (~> 2.9)
       grape (~> 2.0)
+      grape-entity (~> 1.0)
+      grape-swagger (~> 2.1)
+      grape-swagger-entity (~> 0.5)
+      httparty (~> 0.22)
       rack (~> 3.0)
       rackup (~> 2.1)
       statsd-instrument (~> 3.7)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (7.1.3.2)
+    activesupport (7.1.3.4)
       base64
       bigdecimal
       concurrent-ruby (~> 1.0, >= 1.0.2)
@@ -20,12 +34,17 @@ GEM
       minitest (>= 5.1)
       mutex_m
       tzinfo (~> 2.0)
+    adal (1.0.0)
+      jwt (~> 1.5)
+      nokogiri (~> 1.6)
+      uri_template (~> 0.7)
     ast (2.4.2)
     base64 (0.2.0)
     bigdecimal (3.1.8)
-    builder (3.2.4)
-    concurrent-ruby (1.2.3)
+    builder (3.3.0)
+    concurrent-ruby (1.3.1)
     connection_pool (2.4.1)
+    csv (3.3.0)
     diff-lcs (1.5.1)
     docile (1.4.0)
     drb (2.2.1)
@@ -46,29 +65,59 @@ GEM
       zeitwerk (~> 2.6)
     factory_bot (6.4.6)
       activesupport (>= 5.0.0)
+    faraday (2.9.1)
+      faraday-net_http (>= 2.0, < 3.2)
+    faraday-net_http (3.1.0)
+      net-http
     grape (2.0.0)
       activesupport (>= 5)
       builder
       dry-types (>= 1.1)
       mustermann-grape (~> 1.0.0)
       rack (>= 1.3.0)
       rack-accept
+    grape-entity (1.0.1)
+      activesupport (>= 3.0.0)
+      multi_json (>= 1.3.2)
+    grape-swagger (2.1.0)
+      grape (>= 1.7, < 3.0)
+      rack-test (~> 2)
+    grape-swagger-entity (0.5.4)
+      grape-entity (~> 1)
+      grape-swagger (~> 2)
+    httparty (0.22.0)
+      csv
+      mini_mime (>= 1.0.0)
+      multi_xml (>= 0.5.2)
     i18n (1.14.5)
       concurrent-ruby (~> 1.0)
     json (2.7.2)
+    jwt (1.5.6)
     language_server-protocol (3.17.0.3)
-    minitest (5.22.3)
+    mini_mime (1.1.5)
+    mini_portile2 (2.8.7)
+    minitest (5.23.1)
+    multi_json (1.15.0)
+    multi_xml (0.7.1)
+      bigdecimal (~> 3.1)
     mustermann (3.0.0)
       ruby2_keywords (~> 0.0.1)
     mustermann-grape (1.0.2)
       mustermann (>= 1.0.0)
     mutex_m (0.2.0)
+    net-http (0.4.1)
+      uri
+    nokogiri (1.16.5)
+      mini_portile2 (~> 2.8.2)
+      racc (~> 1.4)
+    nokogiri (1.16.5-arm64-darwin)
+      racc (~> 1.4)
     parallel (1.24.0)
-    parser (3.3.1.0)
+    parser (3.3.2.0)
       ast (~> 2.4.1)
       racc
-    racc (1.7.3)
-    rack (3.0.10)
+    racc (1.8.0)
+    rack (3.0.11)
     rack-accept (0.4.5)
       rack (>= 0.4)
     rack-test (2.1.0)
@@ -78,8 +127,9 @@ GEM
       webrick (~> 1.8)
     rainbow (3.1.1)
     rake (13.2.1)
-    regexp_parser (2.9.0)
-    rexml (3.2.6)
+    regexp_parser (2.9.2)
+    rexml (3.2.8)
+      strscan (>= 3.0.9)
     rspec (3.13.0)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
@@ -91,11 +141,11 @@ GEM
       rspec-support (~> 3.13.0)
     rspec-github (2.4.0)
       rspec-core (~> 3.0)
-    rspec-mocks (3.13.0)
+    rspec-mocks (3.13.1)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.1)
-    rubocop (1.63.4)
+    rubocop (1.64.1)
       json (~> 2.3)
       language_server-protocol (>= 3.17.0)
       parallel (~> 1.10)
@@ -114,7 +164,7 @@ GEM
       rubocop (~> 1.41)
     rubocop-rake (0.6.0)
       rubocop (~> 1.0)
-    rubocop-rspec (2.29.2)
+    rubocop-rspec (2.30.0)
       rubocop (~> 1.40)
       rubocop-capybara (~> 2.17)
       rubocop-factory_bot (~> 2.22)
@@ -130,11 +180,14 @@ GEM
     simplecov-html (0.12.3)
     simplecov_json_formatter (0.1.4)
     statsd-instrument (3.7.0)
+    strscan (3.1.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
     unicode-display_width (2.5.0)
+    uri (0.13.0)
+    uri_template (0.7.0)
     webrick (1.8.1)
-    zeitwerk (2.6.13)
+    zeitwerk (2.6.15)
 
 PLATFORMS
   arm64-darwin-23
@@ -143,6 +196,7 @@ PLATFORMS
 DEPENDENCIES
   document-transfer-service!
   factory_bot (~> 6.2)
+  microsoft-graph-client!
   rack-test (~> 2.1)
   rake (~> 13.0)
   rspec (~> 3.12)

README.md

@@ -2,6 +2,27 @@
 
 A microservice to securely transfer documents.
 
+## Configuration
+
+The service is configured using a series of environment variables. The actual
+variables required will depend on the [source] and [destination] types you wish
+to support.
+
+A [sample `.env` file][.env] has been included to help you get started. Simply
+copy this file to `.env` and update the values as needed.
+
+Make sure this file is then loaded into your environment before running the
+service. This can be done automatically through various shell tools (such as
+[Oh My Zsh][omz]), or manually by running the following:
+
+```bash
+source .env
+```
+
+_Note: Your `.env` file will contain sensitive information. This file is ignored
+by git, but it is your responsibility to ensure this file remains safe and
+secure._
+
 ## Running
 
 ### Docker
@@ -35,6 +56,16 @@ bundle exec rackup
 
 The service should now be available at `http://localhost:9292`.
 
+## Usage
+
+See the [API documentation][api] for information on how to interact with the
+service.
+
+[.env]: ./sample.env
+[api]: ./doc/api.md
+[destination]: ./doc/destinations.md
 [Dockerfile]: ./Dockerfile
 [docker compose]: ./docker-compose.yaml
 [Docker Desktop]: https://docs.docker.com/desktop/
+[omz]: https://ohmyz.sh/
+[source]: ./doc/sources.md

Rakefile

@@ -1,10 +1,17 @@
 # frozen_string_literal: true
 
+require 'grape-swagger/rake/oapi_tasks'
 require 'rspec/core/rake_task'
 require 'rubocop/rake_task'
 
 task default: %i[spec rubocop]
 
+task :environment do # rubocop:disable Rake/Desc
+  require_relative 'lib/api/api'
+end
+
+GrapeSwagger::Rake::OapiTasks.new('::DocumentTransfer::API::API')
+
 RuboCop::RakeTask.new(:rubocop) do |task|
   task.requires << 'rubocop'
 end

config.ru

@@ -2,4 +2,6 @@
 
 require_relative 'lib/api/api'
 
-run DocumentService::API
+use Rack::RewindableInput::Middleware
+
+run DocumentTransfer::API::API

doc/api.md

@@ -0,0 +1,59 @@
+# Document Transfer Service API
+
+Interacting with the Document Transfer Service is done through a RESTful API.
+All requests and responses should be in JSON format, unless otherwise indicated.
+
+Full API documentation can be found in the [OpenAPI specification][spec].
+
+## GET /health
+
+A basic health endpoint that will return a 200 status code if the API is
+running.
+
+_Note: This endpoint does not require authentication._
+
+Example response:
+
+```json
+{ "status": "ok" }
+```
+
+## POST /transfer
+
+Initiate a document transfer. This is a synchronous request that will return
+once the transfer is complete or a failure occurs.
+
+The required parameters for this request will vary based on the [source] and
+[destination] types.
+
+Successful requests will always include a `status` and `destination` field.
+Additional fields may be included based on the destination type.
+
+### Example request
+
+```json
+{
+  "source": {
+    "type": "url",
+    "url": "https://example.com/document.pdf"
+  },
+  "destination": {
+    "type": "onedrive",
+    "path": "/document/path"
+  }
+}
+```
+
+### Example response:
+
+```json
+{
+  "status": "success",
+  "destination": "onedrive",
+  "path": "/document/path/document.pdf"
+}
+```
+
+[destination]: destinations.md
+[source]: sources.md
+[spec]: ../openapi.yaml