Allow endpoint owners to create custom actions to make HTTP requests

Requirement

As an endpoint owner and provided that the instance administrator allows this, I would like to be able to create custom actions that, when invoked, result in an HTTP request, optionally with some data, to a URL of my choice. This is in order that endpoint owners can contribute additional interactivity to their own endpoints without running their own code in the instance itself.

Notes

How to add a custom command?

Via ad hoc commands.

For each custom command, the component will ask the following data:

  • Prefix: The text to use as an action prefix. Must not conflict with instance-wide prefixes.
  • Short description: A one-line description of the prefix.
  • Long description: An optional multi-line description.
  • Auth info: Authorisation or authentication information used by the remote endpoint to validate the request.
  • URL: The remote URL.
  • Method: The HTTP method to use.
  • Use response body: Whether the response body will be sent to the invoking user (or MUC) as an XMPP message. For this, the response type should be text/plain.
  • HTTP response code message 1‒5: A series of five HTTP response code / Message text key / value pairs, translating an HTTP status code into a human readable message. For instance: 200 → Command OK; 400 → Command error; etc. Should also accept prefixes, like 2* → Success; 4* → Command failure; 5* → Server failure. The corresponding text will be sent (before the response body, if Use response body is active) to the invoking user (or MUC) as an XMPP message. If no entry matches the response code, nothing is printed.
  • Whitelist: A regular expression, or series of regular expressions, matching who is authorised to invoke this action. Default is everyone can invoke.
  • Blacklist: As above, but to deny access. Default is nobody is blocked.

Structure of the HTTP request

Parameters:

  • prefix
  • body
  • invoker
  • tstamp

If the method is HEAD, GET OPTIONS or DELETE, the above will be sent as query parameters. If the method is POST or PUT, they will be sent in the request body as JSON.

User feedback

  • When the component receives a custom action, it should send a message delivery receipt and a <composing/> chat state notification to supporting entities.
  • When the HTTP request to the remote server completes, or after 30 seconds if taking longer, the component should send a <paused/> chat state notification.
  • If the HTTP request completes, the component should send a <displayed/> chat marker to supporting entities, unless the status code is 5xx.