replace xml file delivery with http push based system (eventing shiggalawahnsinn)

[hairmare]

The idea is to replace the current ssh file-delivery approach with a http POST based API. Here is a bunch of links to previous work pertaining to this change:

• Replace now_playing XML input with modern replacements nowplaying#38
• Replace now_playing XML input with modern replacements nowplaying#38 (comment)
• https://github.com/radiorabe/events-spec (high level docs on events, overengineered)
• https://github.com/orgs/radiorabe/projects/3 (project board)
• feat: evented track input nowplaying#140 (needs to be merged and deployed for this to be ready for implementation)
• https://github.com/radiorabe/nowplaying/milestone/1
• Define RFC 4078 (CRID) spec crid-spec#1

I plan on supporting both XML file delivery and the new HTTP API in a coming nowplaying v2.x release so we don't need to switch over klangbecken at the same time. Support for the current XML file delivery mechanism will then be dropped in nowplaying v3 which is going to be released way after we switch klangbecken to use the new api.

Example Client

This is based on the same python-sdk used on the nowplaying side. The same can be acheived with any client that can send POST requests and headers, see the cURL example below for a simple bash example that demonstrates how the request works.

import requests

from cloudevents.http import CloudEvent, to_structured

def send_event(url, username, password):
    # This data defines a cloudevent
    attributes = {
        "specversion": "1.0",
        # as defined by the events-spec repo
        "type": "ch.rabe.api.events.track.v1.trackStarted",
        # for klangbecken the github link is always used as source (as per events-spec)
        "source": "https://github.com/radiorabe/klangbecken",
        # this should reference the actual broadcast and not some digital representation of it
        # one way to do thas is to use RFC 4087 `crid://` URLs as per the upcoming crid-spec thing.
        "id": "crid://rabe.ch/v1/klangbecken#t=clock=20220209T010400.00Z",
    }
    data = {
        "item.title": "Track Title",
        "item.artist": "Artist",
        # length in seconds, optional if you also implement sending the
        # not "completely specced yet" trackFinished event
        "item.length": 60,
    }

    event = CloudEvent(attributes, data)
    headers, body = to_structured(event)

    # send and print event
    requests.post(url, headers=headers, data=body, auth=(username, password))
    print(f"Sent {event['id']} from {event['source']} with {event.data}")

if __name__ == "__main__":
    # local config
    url = "https://nowplaing.service.int.example.org/webhook"
    username = "rabe"
    password = "rabe"

    # do work
    send_event(url, username, password)

The same event could be sent using cURL:

cat << EOF > event.json
{
    "specversion": "1.0",
    "type": "ch.rabe.api.events.track.v1.trackStarted",
    "source": "https://github.com/radiorabe/klangbecken",
    "id": "crid://rabe.ch/v1/klangbecken#t=clock=20211228T193100.00Z",
    "time": "2021-12-28T19:31:00Z",
    "datacontenttype": "application/json",
    "data": {
        "item.title": "Track Title",
        "item.artist": "Artist",
        "item.length": 60
    }
}
EOF
curl -vvv -u rabe:rabe -H 'Content-Type: application/json' -X POST -d '@event.json' \
  https://nowplaying.service.int.example.org/webhook

In the python-sdk example the time and datacontenttype are autogenerated. The fields are mandatory in any case.

The data fields are based on both the DAB+ MOT SLS/DL+ and ID3 standards as documented in the linked events-spec.

It might make sense to only send these events when klangbecken considers itself onair, i'm not sure about this yet tho.

For generating the CRIDs, there is also rabe-cridlib if that helps.

Tasks

• finish crid spec for use as "id" Define RFC 4078 (CRID) spec crid-spec#1
• implement
• update readme (and drawio thing)