alula-ruby 0.50.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 12adde5899a82d4987e9babe90aaf6db9798e092461fa9332d58d6f57abf8a29
+  data.tar.gz: d149bfe4009b83514fc9935e886f0c08c22749df42b4e3dfb9e8c24df95b293e
+SHA512:
+  metadata.gz: 4d309a84193c63371e8ac6740a015c4ce0b60d802c3b25ca921ec2d212ee769c180cea34f895e211052ab326221392393a09dd2b1fee46deff876aca020d00c9
+  data.tar.gz: 657c5fcbfcebfe04d7d1e6ecd96913b854b9031a5ea8b28309bfe672e13663a6193f073e8204cbd3bafc29f0b338b85aa2b201995aa6b4a7c77d67d11ca4a954

data/.circleci/config.yml

@@ -0,0 +1,14 @@
+version: 2
+jobs:
+  build:
+    machine: true
+    steps:
+      - checkout
+      ## Launch ipdapi stack
+      - run: docker-compose -f alula-docker-compose.yml up -d
+      ## Prepare ruby container to execute tests
+      - run: docker-compose build
+      - run: docker-compose run --name alula-ruby-build alula-ruby bin/setup
+      - run: docker commit alula-ruby-build alula-ruby
+      ## Execute tests
+      - run: docker-compose run alula-ruby bundle exec rspec

data/.env.example

@@ -0,0 +1,8 @@
+CLIENT_ID=<oauth_id>
+CLIENT_SECRET=<oauth_secret>
+API_URL=<api_url>
+DEALER_ACCOUNT_UN=<dealer_account>
+DEALER_ACCOUNT_PW=<dealer_password>
+ADMIN_ACCOUNT_UN=<admin_username>
+ADMIN_ACCOUNT_PW=<admin_password>
+TEST_ACCESS_TOKEN=<test_access_token>

data/.github/workflows/gem-push.yml

@@ -0,0 +1,45 @@
+name: Ruby Gem
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  build:
+    name: Build + Publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby 2.6
+      uses: actions/setup-ruby@v1
+      with:
+        ruby-version: 2.6.x
+
+    - name: Publish to GPR
+      run: |
+        mkdir -p $HOME/.gem
+        touch $HOME/.gem/credentials
+        chmod 0600 $HOME/.gem/credentials
+        printf -- "---\n:github: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
+        gem build *.gemspec
+        gem push --KEY github --host https://rubygems.pkg.github.com/${OWNER} *.gem
+      env:
+        GEM_HOST_API_KEY: "Bearer ${{secrets.GITHUB_TOKEN}}"
+        OWNER: ${{ github.repository_owner }}
+
+    - name: Publish to RubyGems
+      run: |
+        mkdir -p $HOME/.gem
+        touch $HOME/.gem/credentials
+        chmod 0600 $HOME/.gem/credentials
+        printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
+        gem build *.gemspec
+        gem push *.gem
+      env:
+        GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_AUTH_TOKEN}}"

data/.gitignore

@@ -0,0 +1,23 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/data/generated/
+/data/resource_fixtures/
+
+# rspec failure tracking
+.rspec_status
+.byebug_history
+.env
+
+.DS_Store
+
+*.sublime-project
+*.sublime-workspace
+.idea
+spec/testDataResult.json
+/Gemfile.lock

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,7 @@
+---
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 2.5.2
+before_install: gem install bundler -v 2.0.1

data/Dockerfile

@@ -0,0 +1,6 @@
+FROM ruby:2.6-alpine
+
+RUN gem install bundler
+
+RUN apk add bash git build-base jq curl
+

data/Gemfile

@@ -0,0 +1,12 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in alula.gemspec
+gemspec
+
+group :development do
+  platforms :mri do
+    gem "byebug"
+    gem "pry"
+    gem "pry-byebug"
+  end
+end

data/Guardfile

@@ -0,0 +1,42 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+## Uncomment and set this to only include directories you want to watch
+# directories %w(app lib config test spec features) \
+#  .select{|d| Dir.exist?(d) ? d : UI.warning("Directory #{d} does not exist")}
+
+## Note: if you are using the `directories` clause above and you are not
+## watching the project directory ('.'), then you will want to move
+## the Guardfile to a watched dir and symlink it back, e.g.
+#
+#  $ mkdir config
+#  $ mv Guardfile config/
+#  $ ln -s config/Guardfile .
+#
+# and, you'll have to watch "config/Guardfile" instead of "Guardfile"
+
+# Note: The cmd option is now required due to the increasing number of ways
+#       rspec may be run, below are examples of the most common uses.
+#  * bundler: 'bundle exec rspec'
+#  * bundler binstubs: 'bin/rspec'
+#  * spring: 'bin/rspec' (This will use spring if running and you have
+#                          installed the spring binstubs per the docs)
+#  * zeus: 'zeus rspec' (requires the server to be started separately)
+#  * 'just' rspec: 'rspec'
+
+guard :rspec, cmd: "bundle exec rspec" do
+  require "guard/rspec/dsl"
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # Feel free to open issues for suggestions and improvements
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+end

data/README.md

@@ -0,0 +1,423 @@
+# Alula-Ruby
+
+This is the official Alula ruby API client.
+
+## Installation
+
+This gem is private, and can be installed via bundler using a Git fetch strategy:
+
+```ruby
+gem 'alula-ruby', git: "git@github.com:alula-net/alula-ruby.git", tag: 'v0.2.0'
+```
+
+If you use `Sidekiq` and plan on using the Alula-Ruby gem in your Sidekiq workers, you should also bundle the `RequestStore-Sidekiq` extension. This extension is used to store client authorization info in `Thread.current` for multithreading support.
+
+```ruby
+gem 'request_store-sidekiq', '~> 0.1'
+```
+
+And then execute:
+
+    $ bundle
+
+## Authorization
+
+Alula-Ruby requires an OAuth access token to use. You can obtain a token like so:
+
+```ruby
+# Authorize the OAuth client
+Alula::Oauth.configure(client_id: "your client id", client_secret: "your client secret", api_url: "the API URL")
+
+# Obtain OAuth tokens with username & password
+creds = Alula::Oauth.authenticate(username: "a username", password: "a password")
+
+#> creds.token_type = bearer
+#> creds.access_token = some string
+#> creds.refresh_token = some string
+#> creds.expires_in = integer
+#> creds.scope = string
+
+```
+
+## Configuring
+
+```ruby
+Alula::Client.api_key = your API key
+Alula::Client.api_url = The environment URL you will be accessing
+Alula::Client.user_agent = A short name for your script/application
+```
+
+## Usage
+
+Once you have obtained an access token, configure the client to use that token. You should perform this initialization at the start of every request, and at the start of any thread that performs work. The Alula-Ruby client uses the `RequestStore` gem to stash its configuration data in `Thread.current`, so keep this limitation in mind.
+
+```ruby
+Alula::Client.api_key = "your access token"
+```
+
+If you need to save any records, you will also need to tell the `Alula::Client` about your users' authorized role. Depending on the role certain fields may be writeable or protected. You can set your role one of 3 ways:
+
+```ruby
+myself = Alula::Self.retrieve
+
+# The user role is inferred from the Alula::Self object
+Alula::Client.role = myself
+
+# Explicitly set the role via a role symbol
+Alula::Client.role = :dealer
+
+# Explicitly set the role via a u_type integer
+Alula::Client.u_type = 8
+```
+
+Any method will do, you just need to perform one of these prior to attempting to save a resource. Role symbols map to uType resources. The Alula Gem supports the following roles & their corrisponding uType:
+
+```
+| Name          | uType | Role           | Description                            |
+|---------------|-------|----------------|----------------------------------------|
+| System        | 2     | :system        | Highly-privileged system user          |
+| Station       | 4     | :station       | Central station user                   |
+| Dealer        | 8     | :dealer        | Dealer user; child of station users    |
+| Technician    | 16    | :technician    | Technician user; child of dealer users |
+| User          | 32    | :user          | Normal user; child of dealer users     |
+| Sub-User      | 64    | :sub_user      | Child user; child of normal users      |
+| User/Sub-User | 96    | :user_sub_user | Child user; child of normal users      |
+```
+
+See the official Alula API docs for a detailed breakdown of which fields on which resources are changable by which roles.
+
+A Hash object is provided on the `Alula::User` model mapping `uType` to `Role`:
+
+```ruby
+pp Alula::User::UTYPE_ROLE_MAP
+{
+  2  => :system,
+  4  => :station,
+  8  => :dealer,
+  16 => :technician,
+  32 => :user,
+  64 => :sub_user,
+  96 => :user_sub_user
+}
+```
+
+### Retrieving Records
+
+Records can be fetched as a single record:
+
+```ruby
+# Fetch a single device
+device = Alula::Device.retrieve(device_id)
+
+device.friendly_name
+
+#> 'Test Device'
+
+# Fetch singleton resources, like self, without an ID
+me = Alula::Self.retrieve
+```
+
+Collections of records can also be fetched:
+
+```ruby
+# Fetch devices
+devices = Alula::Device.list
+
+# Fetch user data
+users = Alula::User.list
+```
+
+#### Paging collections
+
+Collections can be paginated
+
+```ruby
+# Use .offset to request different pages
+devices = Alula::Device.offset(2).list
+
+# Use .size to change the default page size
+devices = Alula::Device.size(100).list
+
+# Use together
+devices = Alula::Device.offset(20).size(25).list
+
+# A raw .page method is offered:
+devices = Alula::Device.page(size: 20, number: 2).list
+```
+
+#### Sorting collections
+
+Collections can be sorted. See the Alula API documentation for details of which fields can be sorted.
+
+```ruby
+devices = Alula::DeviceEventLog.sort(date_entered: :desc).where_like(mac: '%54%').list
+```
+
+#### Including related models
+
+Many models relate to other models. When loading a model you can specify related models to 'include' in the fetch, and if they exist they will be available on the model.
+
+An `Alula::Device` has a single `Dealer` that relates to it, as defined in the Device metadata:
+
+`relationship :dealer, type: 'dealers', cardinality: 'To-one'`
+
+When you load the Device with and include the Dealer, any available `Dealer` data will become available as an `Alula::Dealer` object like so:
+
+```ruby
+device = Alula::Device.includes(:dealer).retrieve(some_id)
+puts device.dealer
+# A Dealer model will be output here
+puts device.dealer.company_name
+# A company name here...
+```
+
+`TODO: This section is in progress! We are missing many models, so not all relationships are ready for inclusion.`
+
+#### Filter collections
+
+Collections of records can be filtered against using a fluent query API. Check the API documentation to see which fields can be filtered for each model. Errors will be raised when invalid field filter options are selected.
+
+Filters directly map to their [Sequelize operator](https://sequelize.org/master/manual/querying.html#operators), when composing complex queries it is helpful to know how the Sequelize operators work.
+
+*Field Names*
+
+All filters take field names as hash keys, and filter values as hash values. You can use the camelCase representation of each field, or a snake_case represenation. Internally all keys are cast to snake_case for validation, and to camelCase for actual querying.
+
+*$where filter*
+
+The `$where` filter is the most basic filter. It creates an exact match for any fields passed in:
+
+```ruby
+devices = Alula::Device.where(friendly_name: 'TitusTestDevice', program_id: 33).list
+devices = Alula::Device.where(friendly_name: 'TitusTestDevice').where(program_id: 33).list
+```
+
+*$and filter*
+
+The `$and` filter is very similar to the `$where` filter. Unlike `$where`, each field passed into the `$and` filter will be wrapped in the explicit `$and` clause.
+
+
+```ruby
+devices = Alula::Device.and(friendly_name: 'TitusTestDevice', program_id: 33).list
+```
+
+*$like and $notLike filters*
+
+The `$like` and `$notLike` filters allow for wildcard searches across multiple fields.
+
+```ruby
+# Find all devices where the friendly_name starts with 'Titus'
+devices = Alula::Device.like(friendly_name: 'Titus%').list
+
+# Find all devices where the term 'Titus' is not present in the friendly_name
+devices = Alula::Device.not_like(friendly_name: '%Titus%').list
+```
+
+*$in and $notIn filters*
+
+The `$in` and `$notIn` filters accept an array of matches to be queried. The values should be simple values, numbers, strings, and ISO8601 string representations of dates.
+
+```ruby
+# Find records with a value containing one of an array of values
+devices = Alula::Device.in(program_id: [1, 22, 39]).list
+
+# Exclude records with an array of values
+devices = Alula::Device.not_in(program_id: [8, 33, 1]).list
+```
+
+*$between and $notBetween filters*
+
+The `$between` and `$notBetween` filters are similar to an `$in` query, but they take an array of 2 values and request records between those values. Pass in numbers, ISO8601-formatted date strings, or strings where MariaDB can figure out what it means to be "between" each string.
+
+```ruby
+# Find records created between dates
+customers = Alula::User.between(date_entered: [1.year.ago.iso8601, Time.now.iso8601]).list
+
+# Find records outside of a range of values
+devices = Alula::Device.not_between(online_status_timestamp: [1.week.ago.to_i, Time.now.to_i]).list
+```
+
+*$not and $ne filters*
+
+The `$not` and `$ne` filters ($ne for Not Equivilant) operators are roughly analagous, though they use different matchers when constructing their SQL queries.
+
+```ruby
+# Where a field is not strictly a value
+devices = Alula::Device.not(friendly_name: 'TitusTestDevice').list
+
+# Where a field is not equivilant to a value
+devices = Alula::Device.ne(program_id: '2').list
+```
+
+*$lt, $lte, $gt, $gte filters*
+
+The family of less-than, less-than-or-equal, greater-than, and greater-than-or-equal filters all works the same way. They accept a scalar value, a number or ISO8601 date string, and return records that match their constraints.
+
+```ruby
+devices = Alula::Device.gt(:online_status_timestamp: 1.year.ago.to_i).list
+devices = Alula::Device.gte(:online_status_timestamp: 1.year.ago.to_i).list
+
+devices = Alula::Device.lt(:online_status_timestamp: 1.week.ago.to_i).list
+devices = Alula::Device.lte(:online_status_timestamp: 1.week.ago.to_i).list
+```
+
+*$or filters*
+
+The `$or` filter is unique in how it is called, and how it constructs a query. `$or` can take any nested set of other filter operators, so you can combine `$like` and `$in` filters into a single `$or` query to retrieve a broad set of records.
+
+The `$or` filter provides a strict match key->value interface, and a fluent block interface.
+
+```ruby
+# Build an $or query for strict field values
+# Will return any device with the friendly_name 'TitusTestDevice' OR a program_id of 33
+devices = Alula::Device.or(friendly_name: 'TitusTestDevice', program_id: 33).list
+
+# Build an expressive $or query
+# The provided `query_builder` param allows full access to the filter API
+# This will search for devices with a program_id of 2, 33, 85, or 12,
+# where the friendly_name contains 'Helix', and no device is of program_id 2
+#
+devices = Alula::Device.or do |query_builder|
+  query_builder.in(program_id: [2, 33, 85, 12])
+               .like(friendly_name: '%Helix%')
+end
+devices = devices.not(program_id: 5).page(20).list
+```
+
+*$or $like filters*
+
+The OR LIKE pattern is commonly used to do a wildcard search for a term across a bunch of fields at the same time. A shorthand query method is provided to make this easier. As this is a LIKE query, you can use wildcards (`%`) in your term.
+
+```ruby
+devices = Alula::Device.or_like(friendy_name: '%Titus%', email: '%@alula.net').list
+```
+
+*Constructing your own filters*
+
+You can build your own JSON API-compliant filters with the `.filter` method if any of the built in operators do not work for you. Be aware that you *must* use the `camelCase` field name format, and no validation is performed against your query.
+
+```ruby
+# All devices with a strict friendly_name match and an $in query on the program_id
+devices = Alula::Device.filter({
+            friendlyName: 'TitusTestDevice',
+            $or: {
+              $in: {
+                programId: [2, 10]
+              }
+            }
+          }).list
+```
+
+*Debugging Filters*
+
+Before calling `.list` to execute your query, you can call `.as_json`, and be given a JSON representation of your built query. Be aware multiple filters against the same field may overwrite one another, so get a JSON dump to ensure that your assembled query is in the form you intend.
+
+*Supported API filter methods*
+
+The Alula API supports the following filter methods. Access to these filter methods are provided with Ruby methods on collection objects.
+
+| API Operator  | Ruby Method   |  Value                         |  Comment |
+|---------------|---------------|--------------------------------|----------|
+| $gt           | .gt           |  Scalar; number, date          |  Greater than (numeric) |
+| $gte          | .gte          |  ^ Ditto                       |  Greater than or equal |
+| $lt           | .lt           |  ^ Ditto                       |  Less than |
+| $lte          | .lte          |  ^ Ditto                       |  Less than or equal |
+| $not          | .not          |  Scalar; any                   |  Not |
+| $ne           | .ne           |  Scalar; any                   |  Not equal |
+| $between      | .between      |  Array; numbers, dates         |  Between range |
+| $notBetween   | .not_between  |  ^ Ditto                       |  Not between range |
+| $in           | .in           |  Array; any                    | Array of matches |
+| $notIn        | .notIn        |  Array; any                    | Array of negative matches |
+| $like         | .like         |  Scalar; string                | Match string where % can be wildcard |
+| $notLike      | .not_like     |  Scalar; string                | Negative match string where % can be wildcard |
+| $or           | .or           |  Complex                       |  See example |
+| $and          | .and          |  Array of associative arrays   |  Assoc. array where keys are field names,  values like at top-level |
+
+
+### Saving Records
+
+And you can save records
+
+```ruby
+device.friendly_name = 'Waaaluigi'
+device.save
+#> true
+```
+
+Errors saving are reflected with a `false` return to the save call, and errors on the model:
+
+```ruby
+device.meid = 'Test Test'
+device.save
+#> false
+device.errors.first
+```
+
+### Remote Procedure Calls (RPC)
+
+Alula-Ruby partially supports the Alula API's RPC namespace. All RPC methods use the same style method signature, differing only in what params are passed. See the API documentation for a list of params each method supports.
+
+Each remote procedure call supports a single method, named `call`. This method takes a param list equal to the remote procedures params (underscored, not camelcased).
+
+Responses respond to the method `.ok?` for inferring if an error took place.
+
+Success responses are custom per RPC method. Some provide response data, some do not. Response data is raw JSON and is available via `response.result`, and it will be a Hash or Array.
+
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. You can also run `bundle exec bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, and push git commits and tags.
+
+### Using Docker
+
+Alula Ruby runs its unit & integratin tests against a copy of the API running in Docker. The remote API is cleaned up (DB truncated & re-seeded fresh) between every `describe` or `context` block.
+
+1. Set up local `ipdapi` cluster/swarm using `docker-compose`:
+
+        docker-compose -f alula-docker-compose.yml up -d
+
+    or use the `alula-docker-compose` approach:
+
+        alula-docker-compose -I @test-helper --registry '6z1wlx5zf1.execute-api.us-east-1.amazonaws.com/' -- up -d
+
+1. Configure your shell with some shortcuts. Note: If you don't have these present in your shell nothing will work.
+
+        export API_URL=http://127.0.0.1:8800
+        export ALULA_SWARM_TEST_HELPER_URL=http://127.0.0.1:8850
+        export ALULA_SWARM_TEST_HELPER_PORT=8850        
+
+1. Run the complete test suite:
+
+       `bundle exec rspec`
+
+1. Run a specific test file:
+
+        `bundle exec rspec ./spec/alula/oauth_spec.rb`
+
+1. Run Guard to have tests run on file change
+
+        `bundle exec guard`
+
+1. Update all Docker images to the latest images:
+
+    `docker-compose -f alula-docker-compose.yml pull`
+
+Occasionally under heavy use the dockerized API may lose or drop its databases, resulting in the test suite erroring completly and very quickly. To fix this simply restart the API with `docker-compose -f alula-docker-compose.yml down && docker-compose -f alula-docker-compose.yml up -d`
+
+
+## Releasing
+
+In your PR:
+
+- Update VERSION.md with a new version number and a change list
+- Update `lib/alula/version.rb` with the new version number
+- Execute `bundle install` to update the lockfile
+- Commit these changes & include them in your PR.
+
+After merging your PR:
+
+- Check out `master` and pull to get the latest
+- Run `bundle exec rake release`.
+  _A tag will be pushed to Github and then the UI will ask you input to push to a nonexistant URL. Just spam the enter key and let it error out. It's the tag on github that we care about._

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec