clear-election-sdk 0.0.1

data/lib/clear-election-sdk/factory.rb

@@ -0,0 +1,80 @@
+module ClearElection
+  module Factory
+    def self.seq(key)
+      val = (@seq ||= Hash.new(-1))[key] += 1
+      "#{key}-#{val}"
+    end
+
+    def self.election_uri
+      "http://test.example.com/elections/#{seq(:id)}"
+    end
+
+    def self.agent_uri(what="agent", host:"agents.example.com")
+      "http://#{host}/#{seq(what)}/"
+    end
+
+    def self.election(
+      signin: nil,
+      booth: nil,
+      pollsOpen: nil,
+      pollsClose: nil,
+      writeIn: true
+    )
+      one_month = 60*60*24*30
+      Election.new(
+        name: seq("Election Name"),
+        signin: Election::Agent.new(uri: signin || self.agent_uri("signin")),
+        booth: Election::Agent.new(uri: booth || self.agent_uri("booth")),
+        pollsOpen: (pollsOpen || Time.now - one_month).to_datetime(),
+        pollsClose: (pollsClose || Time.now + one_month).to_datetime(),
+        contests: [
+          Factory.contest(ranked: true, multiplicity: 3, writeIn: writeIn, ncandidates: 3),
+          Factory.contest(ncandidates: 2)
+        ]
+      )
+    end
+
+    def self.contest(ranked: nil, multiplicity: nil, writeIn: nil, ncandidates: 3)
+      Election::Contest.new(
+        contestId: seq(:contestId),
+        name: seq("Contest Name"),
+        ranked: ranked,
+        multiplicity: multiplicity,
+        writeIn: writeIn,
+        candidates: ncandidates.times.map{ Election::Candidate.new(candidateId: seq(:candidateId), name: seq("Candidate Name")) }
+      )
+    end
+
+    def self.ballot(election=nil, ballotId: nil, uniquifier: nil, demographic: nil, invalid: nil, complete: true)
+      election ||= self.election
+      contests = election.contests.dup
+      contests = contests.drop(1) if not complete
+      contests << Factory.contest if invalid == :contestId
+      Ballot.new(
+        ballotId: ballotId || seq(:ballotId),
+        uniquifier: uniquifier || seq(:uniquifier),
+        contests: contests.map { |contest|
+          options = contest.candidates.map(&:candidateId)
+          options << "ABSTAIN"
+          options << "WRITEIN: TestWritein" if contest.writeIn
+          options.shuffle!
+          options.push "Test-Invalid-CandidateId" if invalid == :candidateId
+          options.push "WRITEIN: Test-Unpermitted-Writein" if invalid == :writeIn and not contest.writeIn
+          options.push options.last if invalid == :duplicateChoice
+          nchoices = contest.multiplicity
+          nchoices -= 1 if invalid == :multiplicityTooFew
+          nchoices += 1 if invalid == :multiplicityTooMany
+          Ballot::Contest.new(
+            contestId: contest.contestId,
+            choices: nchoices.times.map {|rank|
+              rank += 1 if invalid == :ranking
+              Ballot::Choice.new(candidateId: options.pop, rank: rank)
+            }
+          )
+        },
+        demographic: demographic
+      )
+    end
+  end
+end
+

data/lib/clear-election-sdk/rspec.rb

@@ -0,0 +1,129 @@
+require "webmock/rspec"
+
+require_relative "factory"
+
+module ClearElection
+  module Rspec
+
+    def self.setup(agent: false)
+      RSpec.configure do |config|
+        config.include Helpers
+        if agent
+          config.before(:each) do
+            setup_my_agent_uri
+          end
+        end
+      end
+    end
+      
+    module Helpers
+      # creates a webmock stub request for an election_uri to return an election
+      def stub_election_uri(election: nil, election_uri: nil, booth: nil, signin: nil, pollsOpen: nil, pollsClose: nil, valid: true)
+        election_uri ||= ClearElection::Factory.election_uri
+        if valid
+          election ||= ClearElection::Factory.election(booth: booth, signin: signin, pollsOpen: pollsOpen, pollsClose: pollsClose)
+          result = { body: JSON.generate(election.as_json) }
+        else
+          result = { status: 404 }
+        end
+        stub_request(:get, election_uri).to_return result
+        election_uri
+      end
+
+      # creates a webmock stub for signin with an access token
+      def stub_election_access_token(election_uri:, election: nil, accessToken: nil, demographic: nil, valid: true)
+        accessToken ||= SecureRandom.hex(10)
+        if valid
+          result = { status: 200, body: JSON.generate(demographic: demographic) }
+        else
+          result = { status: 403 }
+        end
+        election ||= ClearElection.read(election_uri)
+        stub_request(:post, election.signin.uri + "redeem").with(body: {election: election_uri, accessToken: accessToken}).to_return result
+        accessToken
+      end
+
+      # For use in an agent: create a URI that will act in rspec as if
+      # it's URI at which the app was called
+      def setup_my_agent_uri
+        host! URI(my_agent_uri).host
+        allow_any_instance_of(ActionDispatch::Request).to receive(:original_url) { |request|
+          request.base_url + URI(my_agent_uri).path + request.original_fullpath
+        }
+      end
+
+      def my_agent_uri
+        @my_agent_uri ||= ClearElection::Factory.agent_uri(Rails.root.basename)
+      end
+
+      shared_examples "api that verifies election state" do |state|
+        describe "verifies election is #{state}" do
+
+          oneDay = 60*60*24
+
+          case state
+          when :open
+            it "rejects if polls have not opened" do
+              Timecop.travel(election.pollsOpen - oneDay) do
+                api_bound.call
+                expect(response).to have_http_status 403
+                expect(JSON.parse(response.body)["error"]).to match /open/i
+              end
+            end
+            it "rejects if polls have closed" do
+              Timecop.travel(election.pollsClose + oneDay) do
+                api_bound.call
+                expect(response).to have_http_status 403
+                expect(JSON.parse(response.body)["error"]).to match /open/i
+              end
+            end
+
+          when :closed
+            it "rejects if polls have not closed" do
+              Timecop.travel(election.pollsClose - oneDay) do
+                api_bound.call
+                expect(response).to have_http_status 403
+                expect(JSON.parse(response.body)["error"]).to match /closed/i
+              end
+            end
+
+          else
+            raise "Unknown election verification state #{state.inspect}" unless state == :unopen
+            it "rejects if polls have opened" do
+              Timecop.travel(election.pollsOpen + oneDay) do
+                api_bound.call
+                expect(response).to have_http_status 403
+                expect(JSON.parse(response.body)["error"]).to match /open/i
+              end
+            end
+          end
+        end
+      end
+
+      shared_examples "api that validates election URI" do |state: nil, agent: nil|
+
+        describe "verifies election URI" do
+          it "rejects invalid election URI" do
+            apicall.call stub_election_uri(valid: false)
+            expect(response).to have_http_status 422
+            expect(JSON.parse(response.body)["error"]).to match /uri/i
+          end
+
+          it "rejects if I am not #{agent} agent" do
+            apicall.call stub_election_uri() # not passing my_agent_uri
+            expect(response).to have_http_status 422
+            expect(JSON.parse(response.body)["error"]).to match /#{agent} agent/i
+          end if agent
+        end
+
+        let(:election_uri) { stub_election_uri(agent ? { agent => my_agent_uri } : {}) }
+
+        it_behaves_like "api that verifies election state", state do
+          let(:election) { ClearElection.read(election_uri) }
+          let(:api_bound) { -> { apicall.call election_uri } }
+        end if state
+
+      end
+    end
+  end
+end

data/lib/clear-election-sdk/schema.rb

@@ -0,0 +1,43 @@
+module ClearElection
+  module Schema
+    extend self
+
+    def root
+      @root ||= Pathname.new(__FILE__).dirname.parent.parent + "schemas"
+    end
+
+    def _get(group:nil, item:, version:, expand: false)
+      JSON.parse(File.read(root + (group||"") + "#{item}-#{version}.schema.json")).tap { |json|
+        expand_refs!(json) if expand
+      }
+    end
+
+    def election(version: ELECTION_SCHEMA_VERSION)
+      _get(item: "election", version: version)
+    end
+
+    def ballot(version: BALLOT_SCHEMA_VERSION)
+      _get(item: "ballot", version: version)
+    end
+
+    def api(agent, version:)
+      _get(group: "api", item: agent, version:version, expand: true)
+    end
+
+    def expand_refs!(json)
+      json.tap {
+        JSON.recurse_proc json do |item|
+          if Hash === item and uri = item['$ref']
+            uri = URI.parse(uri)
+            if uri.scheme
+              source = uri
+              source = ClearElection::Schema.root.join uri.path.sub(%r{^/}, '') if uri.scheme == 'file'
+              item.delete '$ref'
+              item.merge! expand_refs! JSON.parse source.read
+            end
+          end
+        end
+      }
+    end
+  end
+end

data/lib/clear-election-sdk/version.rb

@@ -0,0 +1,3 @@
+module ClearElection
+  VERSION = "0.0.1"
+end

data/schemas/api/booth-agent-0.0.schema.json

@@ -0,0 +1,91 @@
+{
+  "definitions": {
+    "ballot": { "$ref": "file:/ballot-0.0.schema.json" },
+    "session-request": {
+      "type": "object",
+      "properties": {
+        "election": { "type": "string", "format": "uri" },
+        "accessToken": { "type": "string" }
+      },
+      "required": [ "election", "accessToken" ]
+    },
+    "session-response": {
+      "type": "object",
+      "properties": {
+        "sessionKey": { "type": "string" },
+        "ballot": {
+          "type": "object",
+          "properties": {
+            "ballotId": { "type": "string" },
+            "uniquifiers": {
+              "type": "array",
+              "items": { "type": "string" }
+            }
+          },
+          "required": ["ballotId", "uniquifiers" ]
+        }
+      },
+      "required": [ "sessionKey", "ballot" ]
+    },
+    "cast-request": {
+      "type": "object",
+      "properties": {
+        "sessionKey": { "type": "string" },
+        "ballot": { "$ref": "#/definitions/ballot" }
+      },
+      "required": [ "sessionKey", "ballot" ]
+    },
+    "cast-response": {
+      "type": "null"
+    },
+    "returns-request": {
+      "type": "object",
+      "properties": {
+        "election": { "type": "string", "format": "uri" }
+      },
+      "required": [ "election" ]
+    },
+    "returns-response": {
+      "type": "object",
+      "properties": {
+        "ballotsIssued": { "type": "integer" },
+        "ballotsCast": { "type": "integer" },
+        "ballots": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/ballot" }
+        }
+      },
+      "required": [ "ballotsIssued", "ballotsCast", "ballots" ]
+    }
+  },
+
+  "links": [
+    {
+      "description": "Start a session",
+      "href": "/session",
+      "method": "POST",
+      "rel": "create",
+      "title": "Session",
+      "schema": { "$ref": "#/definitions/session-request" },
+      "targetSchema": { "$ref": "#/definitions/session-response" }
+    },
+    {
+      "description": "Cast a ballot",
+      "href": "/cast",
+      "method": "POST",
+      "rel": "create",
+      "title": "Cast",
+      "schema": { "$ref": "#/definitions/cast-request" },
+      "targetSchema": { "$ref": "#/definitions/cast-response" }
+    },
+    {
+      "description": "Get returns",
+      "href": "/returns",
+      "method": "GET",
+      "rel": "list",
+      "title": "Cast",
+      "schema": { "$ref": "#/definitions/returns-request" },
+      "targetSchema": { "$ref": "#/definitions/returns-response" }
+    }
+  ]
+}

data/schemas/ballot-0.0.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "title": "Ballot",
+  "description": "ClearElection Ballot definition, v0.0",
+  "type": "object",
+  "properties": {
+    "version": { "enum": ["0.0"] },
+    "ballotId": { "type": "string" },
+    "uniquifier": { "type": "string" },
+    "contests": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "contestId": { "type": "string" },
+          "choices": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "candidateId": { "type": "string" }
+              },
+              "required": ["candidateId"]
+            }
+          }
+        },
+        "required": ["contestId", "choices"]
+      }
+    },
+    "demographic": { "type": "object" }
+  },
+  "required": ["version", "ballotId", "uniquifier", "contests"]
+}

data/schemas/election-0.0.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "title": "Election",
+  "description": "ClearElection Election definition, v0.0",
+  "type": "object",
+  "properties": {
+    "version": { "enum": ["0.0"] },
+    "name": { "type": "string" },
+    "agents": {
+      "type": "object",
+      "properties": {
+        "signin": { "$ref": "#/definitions/agent" },
+        "booth": { "$ref": "#/definitions/agent" }
+      }
+    },
+    "schedule": {
+      "type": "object",
+      "properties": {
+        "pollsOpen": { "type": "string", "format": "date-time" },
+        "pollsClose": { "type": "string", "format": "date-time" }
+      }
+    },
+    "contests": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "contestId": { "type": "string" },
+          "name": { "type": "string" },
+          "ranked": { "type": "boolean", "default": false },
+          "multiplicity": { "type": "integer", "default": 1, "minimum": 1 },
+          "writeIn": { "type": "boolean", "default": false },
+          "candidates": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "candidateId": { "type": "string" },
+                "name": { "type": "string" }
+              },
+              "required": ["candidateId", "name"]
+            }
+          }
+        },
+        "required": ["contestId", "name", "candidates"]
+      }
+    }
+  },
+  "required": ["version", "name", "agents", "schedule", "contests"],
+  "definitions": {
+    "agent": {
+      "type": "object",
+      "properties": {
+        "uri": { "type": "string", "format": "uri" }
+      },
+      "required": ["uri"]
+    }
+  }
+}
+