txt: ## dist_zef-jonathanstowe-Lumberjack-Message-JSON.md
  # Lumberjack::Message::JSON
  
  JSON representation of a Lumberjack::Message
  
  ![Build Status](https://github.com/jonathanstowe/Lumberjack-Message-JSON/workflows/CI/badge.svg)
  
  ## Synopsis
  
  ```
  use Lumberjack;
  use Lumberjack::Message::JSON;
  
  my $message = Lumberjack::Message.new(message => 'this is a message');
  $message does Lumberjack::Message::JSON;
  
  my $str = $message.to-json;
  
  ...
  
  my $new-message = (Lumberjack::Message but Lumberjack::Message::JSON).from-json($str);
  
  # Alternatively the derived type can be provided as a constant:
  
  constant JSONMessage = (Lumberjack::Message but Lumberjack::Message::JSON);
  
  ...
  
  ```
  
  ## Description
  
  This is used by Lumberjack::Dispatcher::EventSource, Lumberjack::Dispatcher::Proxy, Lumberjack::Application::PSGI and Lumberjack::Application::WebSocket to serialise and deserialise the Lumberjack::Message to/from JSON for transport over HTTP or websockets.
  
  It is implemented as role that can be mixed at run-time to existing Message objects and to create a derived type to un-marshal to (see the Synopsis.)
  
  Itself it uses `JSON::Class` to provide `to-json` and `from-json` and provides custom marshallers and un-marshallers to ensure that the data is rendered meaningfully in JSON.
  
  The JSON will be something like:
  
  ```
  {
     "backtrace" : [
        {
           "file" : "-e",
           "line" : 1,
           "subname" : "<unit>",
           "code" : {}
        }
     ],
     "message" : "this is a test",
     "class" : {
        "log-level" : 2,
        "is-logger" : false,
        "name" : "Any"
     },
     "level" : 2,
     "when" : "2016-04-12T00:18:34.435650+01:00"
  }
  
  ```
  
  Which reflects the Lumberjack::Message fairly closely. There may of course be more backtrace frames.
  
  The 'class' object in the JSON when de-serialised may cause a temporary type to be created with the name provided if the type is not available on the target system, if "is-logger" is true then it will have the `Lumberjack::Logger` applied and the log-level set. This is done so that the message will appear the same as one created on the local system for a message received from a remote logger.
  
  ## Installation
  
  Assuming you have a working Rakudo installation you should be able to install this with *zef*:
  
  zef install Lumberjack::Message::JSON
  
  ## Support
  
  I originally made this as an internal class to `Lumberjack::Application` but found another use for it, so it may not do everything that your application may need.
  
  Any suggestions/patches/bugs can be reported at <https://github.com/jonathanstowe/Lumberjack-Message-JSON/issues>
  
  ## Copyright and Licence
  
  This is free software, please see the <LICENCE> for further details.
  
  © Jonathan Stowe 2021 -
  