Thin wrapper for the Messages API to handle basic GET and POST operations for message entries.

• Installation
• Configuration
• Methods
• Error Handling
• Logging
• Development
• Publishing
• Tests
• Changelog
• License
• Contributing
  • Code of Conduct
• Security Issues

Ensure you have the credentials configured with bundler, then add the following to your Gemfile:

source 'https://<domain-of-our-private-gem-server>/' do
  gem 'certify_messages'
end

Add the following to your Gemfile to bring in the gem from GitHub:

gem 'certify_messages', git: '[email protected]:USSBA/certify_messages.git', branch: 'develop'

This will pull the head of the develop branch in as a gem. If there are updates to the gem repository, you will need to run bundle update certify_messages to get them.

• Clone this repository
• Add it to the Gemfile with the path:

gem 'certify_messages', path: '<path-to-the-gem-on-your-system>'

Within the host application, set the Certify Messages API URL in config/initializers, you probably also want to include a messages.yml under config to be able to specify the URL based on your environment.

CertifyMessages.configure do |config|
  config.api_key = "your_api_key"
  config.api_url = "http://localhost:3000"
  config.msg_api_version = 1
  config.excon_timeout = 5
end

The api_key is currently unused, but we anticipate adding in an API Gateway layer in the future.

With v1.2.0, the default Excon API connection timeout was lowered to 20 seconds. The gem user can also provide a timeout value in seconds as shown above in the configure block. This value is used for the Excon parameters connect_timeout, read_timeout, and write_timeout.

Refer to the Certify Messages API for more complete documentation and detailed examples of method responses.

Note: The Messages API has multiple versions that support different parameters. For example, v3 may require an application_uuid instead of an application_id. Refer to the API documentation to know which parameters to use depending on the version.

The Gem handles a few basic errors including:

• Bad Request - Raised when API returns the HTTP status code 400
• NotFound - Raised when API returns the HTTP status code 404
• InternalServerError - Raised when API returns the HTTP status code 500
• ServiceUnavailable - Raised when API returns the HTTP status code 503

Otherwise the gem will return more specific errors from the API. Refer to the API Docs for details around the specific error.

A typical error will look something like this:

{:body=>{"message"=>"No message found"}, :status=>404}

Along with returning status error messages for API connection issues, the gem will also log connection errors. The default behavior for this is to use the built in Ruby Logger and honor standard log level protocols. The default log level is set to debug and will output to STDOUT. This can also be configured by the gem user to use the gem consumer application's logger, including the app's environment specific log level.

# example implementation for a Rails app
CertifyMessages.configure do |config|
  config.logger = Rails.logger
  config.log_level = Rails.configuration.log_level
end

After checking out the repo, run bundle install to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

Use bin/console to access the pry console and add the API URL to the gem's config to be able to correctly test commands:

CertifyMessages.configuration.api_url="http://localhost:3001"

While working in the console, you can run reload! to reload any code in the gem so that you do not have to restart the console. This should not reset the manual edits to the configuration as noted above.

To release a new version:

1. Bump the version in lib/*/version.rb
2. Merge into master (optional)
3. Push a tag to GitHub in the form: X.Y.Z or X.Y.Z.pre.myPreReleaseTag

At this point, our CI process will kick-off, run the tests, and push the built gem into our Private Gem server.

To run the test suite, simply run:

rspec

or with verbose output:

rspec -f d

To view the coverage report, open

coverage/index.html

rubocop -D

A secrets pattern file poirot-patterns.txt is included with the app to assist with running Poirot to scan commit history for secrets. It is recommended to run this only the current branch only:

  poirot --patterns poirot-patterns.txt --revlist="develop^..HEAD"

Poirot will return an error status if it finds any secrets in the commit history between HEAD and develop. You can correct these by: removing the secrets and squashing commits or by using something like BFG.

Note that Poirot is hardcoded to run in case-insensitive mode and uses two different regex engines (git log --grep and a 3rd-party Python regex library https://pypi.python.org/pypi/regex/ ). Refer to Lines 121 and 195 in <python_path>/site-packages/poirot/poirot.py. The result is that the 'ssn' matcher will flag on: 'ssn', 'SSN', or 'ssN', etc., which also finds 'className', producing false positive errors in the full rev history. Initially we included the (?c) flag in the SSN matchers: .*(ssn)(?c).*[:=]\s*[0-9-]{9,11} however this is not compatible with all regex engines and causes an error in some cases. During the --revlist="all" full history Poirot runs, this pattern failed silently with the git --grep engine and therefore did not actually run. During the --staged Poirot runs, this pattern fails with a stack trace with the pypi/regex engine. The (?c) pattern has been removed entirely and so the ssn patterns can still flag on false positives like 'className'.

Refer to the changelog for details on gem updates. CHANGELOG

Certify Message is licensed permissively under the Apache License v2.0. A copy of that license is distributed with this software.

We welcome contributions. Please read CONTRIBUTING for how to contribute.

We strive for a welcoming and inclusive environment for the Certify Message project.

Please follow this guidelines in all interactions:

1. Be Respectful: use welcoming and inclusive language.
2. Assume best intentions: seek to understand other's opinions.

Please do not submit an issue on GitHub for a security vulnerability. Please contact the development team through the Certify Help Desk at [email protected].

Be sure to include all the pertinent information.

_{The agency reserves the right to change this policy at any time.}