An experimental LDN inbox server for Event Notification messages.
yarn add ldn-inbox-server
Create required directories
mkdir config inbox public
Copy an example JSON Schema as config/notification_schema.json
from this project.
Start the server:
npx ldn-inbox-server start-server --port 8000
Send a demonstration Event Notifications message:
curl -X POST -H 'Content-Type: application/ld+json' --data-binary '@examples/offer.jsonld' http://localhost:8000/inbox/
Start an inbox handler with a demo handler (that creates an Accept
message in the ./outbox
).
npx ldn-inbox-server handler @inbox -hn ./handler/accept_notification_handler.js
Start an outbox handler that send the notifications that are available outbox:
npx ldn-inbox-server handler @outbox -hn ./handler/send_notification_handler.js
LOG4JS
: log4js logging levelLDN_SERVER_HOST
: LDN inbox hostLDN_SERVER_PORT
: LDN inbox portLDN_SERVER_INBOX_URL
: LDN inbox url (path)LDN_SERVER_INBOX_PATH
: LDN inbox pathLDN_SERVER_ERROR_PATH
: LDN error pathLDN_SERVER_OUTBOX_PATH
: LDN outbox pathLDN_SERVER_PUBLIC_PATH
: public (HTML) pathLDN_SERVER_JSON_SCHEMA
: notification JSON validation schemaLDN_SERVER_BASEURL
: baseurl of the LDN inbox serverLDN_SERVER_INBOX_GLOB
: glob of files to process in inbox directoryLDN_SERVER_HAS_PUBLIC_INBOX
: if true, then public read access is allowed on the inboxLDN_SERVER_HAS_WRITABLE_INBOX
: if true, then public write access is allowed on the inbox
Instead of a single inbox, multiple inboxes can be configured by adding a JSON configuration file to the installation. The JSON file should contain a registry
entry with contains an array of inbox configuration. An example:
{
"registry": [
{ "path": "inbox/.*" ,
"with": {
"url": "inbox/",
"inbox": "./inbox",
"inboxPublic": 1,
"inboxWritable": 1,
"schema": "./config/schema1.json"
}},
{ "path": "inbox2/.*" ,
"with": {
"url": "inbox2/",
"inbox": "./inbox2",
"inboxPublic": 1,
"inboxWritable": 0,
"schema": "./config/schema2.json"
}}
]
}
Server extensions are possible by providing custom inbox and notification handlers. E.g.
npx ldn-inbox-server handler @inbox -hn handler/my_handler.js
Or, in JavaScript:
const { handle_inbox } = require('ldn-inbox-handler');
main();
async function main() {
await handle_inbox('./inbox', {
'inbox': './inbox',
'outbox': './outbox',
'public': './public',
'error': './error',
'batch_size': 5,
'glob': '^.*\\.jsonld$',
'config': './config/inbox_config.json',
'notification_handler': 'handler/my_handler.js'
});
}
with my_handler.js
:
async function handle({path,options}) {
//...
return { path, options, success: true };
}
module.exports = { handle };
A handler can be started on any directory. E.g. a workflow might be:
- have an "inbox" handler to validate incoming LDN messages
- valid LDN messages will be saved into the "accepted" box
- invalid LDN messages will be saved into the "error" box
- have an "accepted" handler to process valid LDN messages
- processed LDN messages will end up in the "outbox" box
- invalid processing will be saved into the "error" box
A handler that creates for an incoming notification an Accept
notification in the @outbox
.
A handler that updates an event log with the incoming notification.
Requires configuration properties:
log
: the path to the event log (starting from thepublic
directory)dir
: the path to a container to store the events (starting from thepublic
directory)
The log
and dir
path may contain a @artifact(:strip)?@
directive to fill in the
path of the current artifact. The :strip
filter is used to strip an artifact path of a file extension. E.g. path/artifact.html
becomes path/artifact
when using a :strip
.
A handler that accepts a notifiction when it matches one or more JSON paths
Requires configuration properties:
- anyOf : an array of json path matchers, the combination should be interpreted as a logical
OR
.- every json path matcher is an array of single matchers, the combination should be interpered as a logical
AND
.
- every json path matcher is an array of single matchers, the combination should be interpered as a logical
A single matcher needs two properties:
- path : a json path
- value : a value
The json path matches when one of:
- On the json path an array is found and the value is included in the array
- On the json path a string or number is found and the value is equal to this string or number
A handler/multi_notification_handler.js
is available to start multiple handler for each notification messages. The handlers to start are specified in a configuration file that can be passed via the config
parameter of an handle_inbox
. In the commmand line tool bin/ldn-inbox-server
the default location of such config file is config/inbox_config.json
when processing an @inbox
, and config/outbox_config.json
when processing an @outbox
.
A handler to Offer
an event log to a memento server.
Requires configuration properties:
actor
: the LDN+AS2actor
to use in a notificationtarget
: the LDN+AS2target
to use in a notification
A handler to send notification that live in the @outbox
via the LDN protocol to the LDN target
.
A handler that accepts any notification with a type that matches one of the anyOf
types.
A handler that validates the incoming notification and checks if the object
or context
contains an artifact that is part of the public
resources. See 'Artifact support' below.
Generates the following options keys:
- artifact.id : the URL of the artifact
- artifact.path : the local path to the artifact
A hander that validates the incoming notification and checks if the object
or context
contains an event log that is part of the public
resources.
Generates the following options keys:
- eventlog.id : the URL of the event log
- eventlog.path : the local path of the event log
This code base contains Event Notifications support for Data Node artifacts. See the examples
in public/artifacts-example
. Move this directory tp public/artifacts
to get a running example.
- Each artifact requires at least a
.meta
file with theX-Artifact
header set totrue
to be recognized by the software as an artifact - Each artifact should update the
Link-Template
header in the.meta
file - The config files in
config/inbox_config.json
andconfig/outbox_config.json
define the location of the possible event logs for the artifact