twiglet 3.0.5 → 3.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44c51be445d04ae84c5289cbeaa7508b9d3f733ce7b8d5001c7925bd0ed44dd4
-  data.tar.gz: 2f04af22bf6c01fd12c8863e3c9350791d0d6c1ffaaf920797f9430e8e9d1e74
+  metadata.gz: 5aa4993d40d0b1f658c6b5f8c79f364e4bc1fef111d094b48446bde0fe7a0701
+  data.tar.gz: 8c6dee85c7622b274d570eb400bb8ca065c70e311a11699a990bc5548a2479d7
 SHA512:
-  metadata.gz: 602d459a46ecb262457ba2b4cd3cb3900c3cdc77b3663087717018911bb61ef921e0892b7a24749182264e1e1ee970b9c92c72663ef0ed587a408de3863f8140
-  data.tar.gz: 342cc5eebdc1054be2ae04c434218eeb93902328bfbed79cf66df4d3445a6604206084d88aae4a5998656138e3edec4eb37421079c3d8a78a6a27f822f399860
+  metadata.gz: 863b7bb7f3848a2345ffe5c8639add2f77fa7849d4f29d873bb25eb97c3510a2edec4c78cc6a95b343c1ee305571ca43534f88b494d983e0f00b23e7dd5ae5d5
+  data.tar.gz: 5827e6d6eee5fb90ca06822f7d5df2ac757a00f5d281453f74c3f3f3efcfee603639003eb711ccb026738ff9cd35e54405fc2ee125eb44b13f413f69f365f4c7

data/.github/workflows/dobby-actions.yml

@@ -0,0 +1,16 @@
+name: "dobby action"
+on:
+  issue_comment:
+    types: [created]
+jobs:
+  pr_commented:
+    runs-on: ubuntu-20.04
+    if: startsWith(github.event.comment.body, '/dobby')
+
+    steps:
+      - name: bump version
+        uses: simplybusiness/dobby@v2.0.0
+        env:
+          DOBBY_APP_ID: ${{ secrets.DOBBY_APP_ID }}
+          DOBBY_PRIVATE_KEY: ${{ secrets.DOBBY_PRIVATE_KEY }}
+          VERSION_FILE_PATH: lib/twiglet/version.rb

data/Gemfile

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 source 'https://rubygems.org'
+
+gem 'json-schema'
+
 group :development, :test do
   gem 'minitest'
   gem 'rake'

data/README.md

@@ -110,7 +110,7 @@ This writes:
 It may be that when making a series of logs that write information about a single event, you may want to avoid duplication by creating an event specific logger that includes the context:
 
 ```ruby
-request_log = logger.with({ event: { action: 'HTTP request'}, trace: { id: '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb' }})
+request_logger = logger.with({ event: { action: 'HTTP request'}, trace: { id: '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb' }})
 ```
 
 This can be used like any other Logger instance:
@@ -140,6 +140,10 @@ To access the formatter:
 logger.formatter
 ```
 
+### HTTP Request Logging
+Take a look at this sample [Rack application](examples/rack/example_rack_app.rb#L15) with an ECS compliant
+[request logger](/examples/rack/request_logger.rb) as a template when configuring your own request logging middleware with Twiglet.
+
 ## Use of dotted keys (DEPRECATED)
 
 Writing nested json objects could be confusing. This library has a built-in feature to convert dotted keys into nested objects, so if you log like this:

data/example_app.rb

@@ -7,28 +7,32 @@ PORT = 8080
 logger = Twiglet::Logger.new('petshop')
 
 # Start our petshop
-logger.info({
-  event: {
-    action: 'startup'
-  },
-  message: "Ready to go, listening on port #{PORT}",
-  server: {
-    port: PORT
+logger.info(
+  {
+    event: {
+      action: 'startup'
+    },
+    message: "Ready to go, listening on port #{PORT}",
+    server: {
+      port: PORT
+    }
   }
-})
+)
 
 # Use text logging
 logger.info("Ready to go, listening on port #{PORT}")
 #
 # We get a request
-request_logger = logger.with({
-  event: {
-    action: 'HTTP request'
-  },
-  trace: {
-    id: '126bb6fa-28a2-470f-b013-eefbf9182b2d'
+request_logger = logger.with(
+  {
+    event: {
+      action: 'HTTP request'
+    },
+    trace: {
+      id: '126bb6fa-28a2-470f-b013-eefbf9182b2d'
+    }
   }
-})
+)
 
 # Oh noes!
 db_err = StandardError.new('Connection timed-out')
@@ -36,17 +40,19 @@ db_err = StandardError.new('Connection timed-out')
 request_logger.error({ message: 'DB connection failed.' }, db_err) if db_err
 
 # We return an error to the requester
-request_logger.info({
-  message: 'Internal Server Error',
-  http: {
-    request: {
-      method: 'get'
-    },
-    response: {
-      status_code: 500
+request_logger.info(
+  {
+    message: 'Internal Server Error',
+    http: {
+      request: {
+        method: 'get'
+      },
+      response: {
+        status_code: 500
+      }
     }
   }
-})
+)
 
 # Logging with an empty message is an anti-pattern and is therefore forbidden
 # Both of the following lines would throw an error

data/examples/rack/request_logger_test.rb

@@ -15,10 +15,12 @@ describe RequestLogger do
   end
 
   it 'logs the request data' do
-    request.get("/some/path?some_var=1", 'HTTP_ACCEPT' => 'application/json',
-                                         'REMOTE_ADDR' => '0.0.0.0',
-                                         'HTTP_VERSION' => 'HTTP/1.1',
-                                         'HTTP_USER_AGENT' => 'Mozilla/5.0 (Macintosh)')
+    request.get(
+      "/some/path?some_var=1", 'HTTP_ACCEPT' => 'application/json',
+                               'REMOTE_ADDR' => '0.0.0.0',
+                               'HTTP_VERSION' => 'HTTP/1.1',
+                               'HTTP_USER_AGENT' => 'Mozilla/5.0 (Macintosh)'
+    )
     log = JSON.parse(output.string)
 
     expected_log = {
@@ -55,7 +57,7 @@ describe RequestLogger do
   end
 
   it 'does not log PII' do
-    request.post("/user/info", input_data: {credit_card_no: '1234'})
+    request.post("/user/info", input_data: { credit_card_no: '1234' })
     log = output.string
     assert_includes log, "POST: /user/info"
     refute_includes log, 'credit_card_no'

data/lib/twiglet/formatter.rb

@@ -1,24 +1,28 @@
 require 'logger'
 require_relative '../hash_extensions'
 require_relative 'message'
+require_relative 'validator'
 
 module Twiglet
   class Formatter < ::Logger::Formatter
     Hash.include HashExtensions
 
     def initialize(service_name,
-                   default_properties: {},
+                   validator:, default_properties: {},
                    now: -> { Time.now.utc })
       @service_name = service_name
       @now = now
       @default_properties = default_properties
+      @validator = validator
 
       super()
     end
 
     def call(severity, _time, _progname, msg)
       level = severity.downcase
-      log(level: level, message: Message.new(msg))
+      message = Message.new(msg)
+      @validator.validate(message)
+      log(level: level, message: message)
     end
 
     private

data/lib/twiglet/logger.rb

@@ -26,16 +26,27 @@ module Twiglet
       raise 'Service name is mandatory' \
         unless service_name.is_a?(String) && !service_name.strip.empty?
 
-      formatter = Twiglet::Formatter.new(service_name, default_properties: default_properties, now: now)
-      super(output, formatter: formatter, level: level)
+      @validator = Validator.from_file("#{__dir__}/validation_schema.json")
+
+      @formatter = Twiglet::Formatter.new(
+        service_name,
+        default_properties: default_properties,
+        now: now,
+        validator: @validator
+      )
+      super(output, formatter: @formatter, level: level)
+    end
+
+    def configure_validation_error_response(&block)
+      @validator.custom_error_handler = block
     end
 
     def error(message = nil, error = nil, &block)
       if error
         error_fields = {
-          'error': {
-            'type': error.class,
-            'message': error.message
+          error: {
+            type: error.class,
+            message: error.message
           }
         }
         add_stack_trace(error_fields, error)
@@ -46,11 +57,13 @@ module Twiglet
     end
 
     def with(default_properties)
-      Logger.new(@service_name,
-                 default_properties: default_properties,
-                 now: @now,
-                 output: @output,
-                 level: @level)
+      Logger.new(
+        @service_name,
+        default_properties: default_properties,
+        now: @now,
+        output: @output,
+        level: @level
+      )
     end
 
     alias_method :warning, :warn

data/lib/twiglet/message.rb

@@ -1,24 +1,15 @@
 module Twiglet
   class Message < Hash
     def initialize(msg)
+      super
       case msg
       when String
         self[:message] = msg
       when Hash
         replace(msg.transform_keys!(&:to_sym))
+      else
+        super(msg)
       end
-
-      validate!
-    end
-
-    private
-
-    def validate!
-      raise 'Message must be initialized with a String or a non-empty Hash' if empty?
-
-      raise 'Log object must have a \'message\' property' unless self[:message]
-
-      raise 'The \'message\' property of the log object must not be empty' if self[:message].strip.empty?
     end
   end
 end

data/lib/twiglet/validation_schema.json

@@ -0,0 +1,10 @@
+{
+  "type": "object",
+  "required": ["message"],
+  "properties": {
+    "message": {
+      "type": "string",
+      "minLength": 1
+    }
+  }
+}

data/lib/twiglet/validator.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'json-schema'
+require 'json'
+
+module Twiglet
+  class Validator
+    attr_accessor :custom_error_handler
+
+    def initialize(schema)
+      @schema = schema
+      @custom_error_handler = ->(e) { raise e }
+    end
+
+    def self.from_file(file_path)
+      new(JSON.parse(File.read(file_path)))
+    end
+
+    def validate(message)
+      JSON::Validator.validate!(@schema, message)
+    rescue JSON::Schema::ValidationError => e
+      custom_error_handler.call(e)
+    end
+  end
+end

data/lib/twiglet/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Twiglet
-  VERSION = '3.0.5'
+  VERSION = '3.1.2'
 end

data/test/formatter_test.rb

@@ -3,11 +3,12 @@
 require 'minitest/autorun'
 require 'json'
 require_relative '../lib/twiglet/formatter'
+require_relative '../lib/twiglet/validator'
 
 describe Twiglet::Formatter do
   before do
     @now = -> { Time.utc(2020, 5, 11, 15, 1, 1) }
-    @formatter = Twiglet::Formatter.new('petshop', now: @now)
+    @formatter = Twiglet::Formatter.new('petshop', now: @now, validator: Twiglet::Validator.new({}))
   end
 
   it 'initializes an instance of a Ruby Logger Formatter' do

data/test/logger_test.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'minitest/autorun'
+require 'minitest/mock'
 require_relative '../lib/twiglet/logger'
 
 LEVELS = [
@@ -18,9 +19,11 @@ describe Twiglet::Logger do
   before do
     @now = -> { Time.utc(2020, 5, 11, 15, 1, 1) }
     @buffer = StringIO.new
-    @logger = Twiglet::Logger.new('petshop',
-                                  now: @now,
-                                  output: @buffer)
+    @logger = Twiglet::Logger.new(
+      'petshop',
+      now: @now,
+      output: @buffer
+    )
   end
 
   it 'should throw an error with an empty service name' do
@@ -30,21 +33,29 @@ describe Twiglet::Logger do
   end
 
   it 'conforms to the standard Ruby Logger API' do
-    [:debug, :debug?, :info, :info?, :warn, :warn?, :fatal, :fatal?, :error, :error?,
-     :level, :level=, :sev_threshold=].each do |call|
+    [
+      :debug, :debug?, :info, :info?, :warn, :warn?, :fatal, :fatal?, :error, :error?,
+      :level, :level=, :sev_threshold=
+    ].each do |call|
       assert @logger.respond_to?(call), "Logger does not respond to #{call}"
     end
   end
 
   describe 'JSON logging' do
     it 'should throw an error with an empty message' do
-      assert_raises RuntimeError do
-        @logger.info({message: ''})
+      assert_raises JSON::Schema::ValidationError, "The property '#/message' was not of a minimum string length of 1" do
+        @logger.info({ message: '' })
+      end
+    end
+
+    it 'should throw an error if message is missing' do
+      assert_raises JSON::Schema::ValidationError, "The property '#/message' was not of a minimum string length of 1" do
+        @logger.info({ foo: 'bar' })
       end
     end
 
     it 'should log mandatory attributes' do
-      @logger.error({message: 'Out of pets exception'})
+      @logger.error({ message: 'Out of pets exception' })
       actual_log = read_json(@buffer)
 
       expected_log = {
@@ -65,9 +76,13 @@ describe Twiglet::Logger do
     end
 
     it 'should log the provided message' do
-      @logger.error({event:
-                       {action: 'exception'},
-                     message: 'Emergency! Emergency!'})
+      @logger.error(
+        {
+          event:
+                                 { action: 'exception' },
+          message: 'Emergency! Emergency!'
+        }
+      )
       log = read_json(@buffer)
 
       assert_equal 'exception', log[:event][:action]
@@ -82,17 +97,19 @@ describe Twiglet::Logger do
         service: {
           type: 'shop'
         },
-        request: {method: 'get'},
-        response: {status_code: 200}
+        request: { method: 'get' },
+        response: { status_code: 200 }
       }
 
       output = StringIO.new
-      logger = Twiglet::Logger.new('petshop',
-                                   now: @now,
-                                   output: output,
-                                   default_properties: extra_properties)
-
-      logger.error({message: 'GET /cats'})
+      logger = Twiglet::Logger.new(
+        'petshop',
+        now: @now,
+        output: output,
+        default_properties: extra_properties
+      )
+
+      logger.error({ message: 'GET /cats' })
       log = read_json output
 
       assert_equal '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb', log[:trace][:id]
@@ -104,17 +121,21 @@ describe Twiglet::Logger do
 
     it "should be able to add properties with '.with'" do
       # Let's add some context to this customer journey
-      purchase_logger = @logger.with({
-        trace: {id: '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb'},
-        customer: {full_name: 'Freda Bloggs'},
-        event: {action: 'pet purchase'}
-      })
+      purchase_logger = @logger.with(
+        {
+          trace: { id: '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb' },
+          customer: { full_name: 'Freda Bloggs' },
+          event: { action: 'pet purchase' }
+        }
+      )
 
       # do stuff
-      purchase_logger.info({
-        message: 'customer bought a dog',
-        pet: {name: 'Barker', species: 'dog', breed: 'Bitsa'}
-      })
+      purchase_logger.info(
+        {
+          message: 'customer bought a dog',
+          pet: { name: 'Barker', species: 'dog', breed: 'Bitsa' }
+        }
+      )
 
       log = read_json @buffer
 
@@ -135,8 +156,8 @@ describe Twiglet::Logger do
     end
 
     it "should log multiple messages properly" do
-      @logger.debug({message: 'hi'})
-      @logger.info({message: 'there'})
+      @logger.debug({ message: 'hi' })
+      @logger.info({ message: 'there' })
 
       expected_output =
         '{"ecs":{"version":"1.5.0"},"@timestamp":"2020-05-11T15:01:01.000Z",'\
@@ -174,7 +195,7 @@ describe Twiglet::Logger do
 
     LEVELS.each do |attrs|
       it "should correctly log level when calling #{attrs[:method]}" do
-        @logger.public_send(attrs[:method], {message: 'a log message'})
+        @logger.public_send(attrs[:method], { message: 'a log message' })
         actual_log = read_json(@buffer)
 
         assert_equal attrs[:level], actual_log[:log][:level]
@@ -188,7 +209,7 @@ describe Twiglet::Logger do
       begin
         1 / 0
       rescue StandardError => e
-        @logger.error({message: 'Artificially raised exception'}, e)
+        @logger.error({ message: 'Artificially raised exception' }, e)
       end
 
       actual_log = read_json(@buffer)
@@ -201,7 +222,7 @@ describe Twiglet::Logger do
 
     it 'should log an error without backtrace' do
       e = StandardError.new('Connection timed-out')
-      @logger.error({message: 'Artificially raised exception'}, e)
+      @logger.error({ message: 'Artificially raised exception' }, e)
 
       actual_log = read_json(@buffer)
 
@@ -225,7 +246,7 @@ describe Twiglet::Logger do
 
   describe 'text logging' do
     it 'should throw an error with an empty message' do
-      assert_raises RuntimeError do
+      assert_raises JSON::Schema::ValidationError, "The property '#/message' was not of a minimum string length of 1" do
         @logger.info('')
       end
     end
@@ -284,13 +305,15 @@ describe Twiglet::Logger do
 
   describe 'dotted keys' do
     it 'should be able to convert dotted keys to nested objects' do
-      @logger.debug({
-        "trace.id": '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb',
-        message: 'customer bought a dog',
-        "pet.name": 'Barker',
-        "pet.species": 'dog',
-        "pet.breed": 'Bitsa'
-      })
+      @logger.debug(
+        {
+          "trace.id": '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb',
+          message: 'customer bought a dog',
+          "pet.name": 'Barker',
+          "pet.species": 'dog',
+          "pet.breed": 'Bitsa'
+        }
+      )
       log = read_json(@buffer)
 
       assert_equal '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb', log[:trace][:id]
@@ -301,12 +324,14 @@ describe Twiglet::Logger do
     end
 
     it 'should be able to mix dotted keys and nested objects' do
-      @logger.debug({
-        "trace.id": '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb',
-        message: 'customer bought a dog',
-        pet: {name: 'Barker', breed: 'Bitsa'},
-        "pet.species": 'dog'
-      })
+      @logger.debug(
+        {
+          "trace.id": '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb',
+          message: 'customer bought a dog',
+          pet: { name: 'Barker', breed: 'Bitsa' },
+          "pet.species": 'dog'
+        }
+      )
       log = read_json(@buffer)
 
       assert_equal '1c8a5fb2-fecd-44d8-92a4-449eb2ce4dcb', log[:trace][:id]
@@ -334,6 +359,27 @@ describe Twiglet::Logger do
     end
   end
 
+  describe 'configuring error response' do
+    it 'blows up by default' do
+      assert_raises JSON::Schema::ValidationError,
+                    "The property '#/message' of type boolean did not match the following type: string" do
+        @logger.debug(message: true)
+      end
+    end
+
+    it 'silently swallows errors when configured to do so' do
+      mock = Minitest::Mock.new
+
+      @logger.configure_validation_error_response do |_e|
+        mock.notify_error("Logging schema validation error")
+      end
+
+      mock.expect(:notify_error, nil, ["Logging schema validation error"])
+      nonconformant_log = { message: true }
+      @logger.debug(nonconformant_log)
+    end
+  end
+
   private
 
   def read_json(buffer)

data/test/message_test.rb

@@ -2,24 +2,6 @@ require 'minitest/autorun'
 require_relative '../lib/twiglet/message'
 
 describe Twiglet::Message do
-  it 'raises if message is empty' do
-    assert_raises RuntimeError do
-      Twiglet::Message.new('   ')
-    end
-  end
-
-  it 'raises if message is not provided' do
-    assert_raises RuntimeError do
-      Twiglet::Message.new(foo: 'bar')
-    end
-  end
-
-  it 'raises on unrecognized inputs' do
-    assert_raises RuntimeError do
-      Twiglet::Message.new(OpenStruct.new(message: 'hello'))
-    end
-  end
-
   it 'returns a message hash from a string' do
     assert_equal Twiglet::Message.new('hello, world'), { message: 'hello, world' }
   end

data/test/test_coverage.rb

@@ -7,7 +7,11 @@ SimpleCov.start do
   if ENV['CI']
     formatter SimpleCov::Formatter::SimpleFormatter
   else
-    formatter SimpleCov::Formatter::MultiFormatter.new([SimpleCov::Formatter::SimpleFormatter,
-                                                        SimpleCov::Formatter::HTMLFormatter])
+    formatter SimpleCov::Formatter::MultiFormatter.new(
+      [
+        SimpleCov::Formatter::SimpleFormatter,
+        SimpleCov::Formatter::HTMLFormatter
+      ]
+    )
   end
 end

data/test/validator_test.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'minitest/autorun'
+require_relative '../lib/twiglet/validator'
+
+describe Twiglet::Validator do
+  let(:valid)
+
+  before do
+    schema = {
+      "type" => "object",
+      "required" => ["message"],
+      "properties" => {
+        "message" => {
+          "type" => "string"
+        }
+      }
+    }
+
+    @validator = Twiglet::Validator.new(schema)
+  end
+
+  it 'does not raise when validation passes' do
+    assert_equal(@validator.validate({ message: 'this is my message', foo: 'bar' }), true)
+  end
+
+  it 'raises when validation fails' do
+    assert_raises JSON::Schema::ValidationError do
+      @validator.validate({ message: true })
+    end
+  end
+
+  it 'is a no-op when validator is configured to swallow errors' do
+    @validator.custom_error_handler = ->(e) { puts e }
+
+    assert_nil(@validator.validate({ message: true }))
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: twiglet
 version: !ruby/object:Gem::Version
-  version: 3.0.5
+  version: 3.1.2
 platform: ruby
 authors:
 - Simply Business
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-01-25 00:00:00.000000000 Z
+date: 2021-02-16 00:00:00.000000000 Z
 dependencies: []
 description: Like a log, only smaller.
 email:
@@ -19,6 +19,7 @@ extra_rdoc_files: []
 files:
 - ".github/CODEOWNERS"
 - ".github/dependabot.yml"
+- ".github/workflows/dobby-actions.yml"
 - ".github/workflows/gem-publish.yml"
 - ".github/workflows/ruby.yml"
 - ".github/workflows/version-forget-me-not.yml"
@@ -41,12 +42,15 @@ files:
 - lib/twiglet/formatter.rb
 - lib/twiglet/logger.rb
 - lib/twiglet/message.rb
+- lib/twiglet/validation_schema.json
+- lib/twiglet/validator.rb
 - lib/twiglet/version.rb
 - test/formatter_test.rb
 - test/hash_extensions_test.rb
 - test/logger_test.rb
 - test/message_test.rb
 - test/test_coverage.rb
+- test/validator_test.rb
 - twiglet.gemspec
 homepage: https://github.com/simplybusiness/twiglet-ruby
 licenses:
@@ -67,7 +71,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.2.3
 signing_key: 
 specification_version: 4
 summary: Twiglet