HTTPd Module

Alfred

Compatibility:

Description

This module runs a webserver, exposing an API to interact with Alfred and botmans.
It also includes a basic website providing a GUI over this API.
Exposed webserver will bind on port 5128.

Configuration

This module does not need any configuration file.

API

/stats/commands/list

This API call will let you retrieve the list of API calls available through this web service.

Using from cURL

curl http://127.0.0.1:5128/stats/commands/list

Output format

[{
   "uri":   "/stats/commands/list",
   "description": "HTML code describing the URI"
},
...
]

/seen

This command allows you to search for botmans.
It uses JID or custom variables to match them.

Querying every botman

curl http://127.0.0.1:5128/seen

Querying only botmans matching a pattern

curl http://127.0.0.1:5128/*backup*

Given pattern will be match against JID and custom variables defined inside seen.conf (from the Seen module).

Possible returned HTTP codes

200	Query OK.
500	HTTPd module encountered an internal error.

Returned data

Data returned will be in JSON format.
It will be an array of contacts matching your pattern.

[
   {
      "jid":   "botman-bull@xmpp-test.asp64.lan",
      "state": "online",
      "vars":  [
        {
          "name":  "version_ecore",
          "value": "1.7.12"
        },
        ...
      ]
   },
   ... ]

/spam

This API call will let you send commands to multiple bots at once.

curl http://127.0.0.1:5128/spam/*

Possible returned HTTP codes

200	Every queried bots answered.
204	Your given pattern did not match any bots (no data will be sent).
206	Some (or all) bots did not answer. In this case, bots that did not answer will have a 0 length message in the returned JSON.

Returned data

Data returned will be in JSON format.
It will be an array of answers from bots.

[
   {
      "jid" : "botman-test@xmpp-server.lan",
      "message" : "Data returned by botman-test"
   }
]

/uptime

This API call will let you retrieve output of the uptime command.

As this command is ran through the spam module, you can query multiple bots at once.
Returned data will be equal to the /spam URI.

curl http://127.0.0.1:5128/uptime/*backup*

/service

This API call will give you access to management of services.

As this command is ran through the spam module, you can query multiple bots at once.
Returned data will be equal to the /spam URI.

URI is separated by at least 2 params:

Service operation: start, stop, restart, status
Service name
Optional pattern matching bots to contact

curl http://127.0.0.1:5128/service/start/servicename/*backup*

/network

This API call will give you to retrieve network informations, fetch by the Network module.

As this command is ran through the spam module, you can query multiple bots at once.
Returned data will be equal to the /spam URI.

curl http://127.0.0.1:5128/network/*backup*

/log/last

This command allows you to query logs sorted by insertion order (newest first).
It is possible to navigate through logs, following the concept of log pages.

Getting last 5 logs

curl http://127.0.0.1:5128/log/last/5

Getting 2nd page of logs, following 5 logs per page

curl http://127.0.0.1:5128/log/last/5/2

Filters

Filters can be applied using the SQL language.
Possible fields to filter:

id: INTEGER: Unique log identifier.
date: DATE: Date of event.
type: INTEGER: 0 (connection) 1 (disconnection) 2 (message)
source: TEXT: JID of user that created event
data: TEXT: if type is 2, contains the XMPP message.

Getting last 5 commands from a given user

curl -d '[ "source = \"JID@domain\"", "data != \"\"" ]' http://127.0.0.1:5128/log/last/5

/stats

This API call will give out various stats about Alfred’s process.

Possible returned HTTP codes

200	Query OK.
500	HTTPd module encountered an internal error.

Returned data

Data returned will be in JSON format.

{
   "uptime":   3,
   "memory":   {
      "used":  64163840
   },
   "contacts": [{
      "jid":   "botman-testdev@xmpp-test.asp64.lan",
      "type":  "Botman",
      "online":   true
   }],
   "queries":  [{
      "ip": "127.0.0.1",
      "uri":   "/seen",
      "data":  "",
      "timestamp":   1463730596
   }]
}

Web UI

As of version 2.0.0 of botman, the Web UI is only 4 pages.

Dashboard (mainpage)

This page groups 3 kind of informations:

System informations: Alfred’s uptime and used memory.
Last 20 queries: Last 20 received queries, be it over XMPP or HTTP.
List of contacts: List alfred's contacts, online status, and type (alfred, botman, user).

Informations displayed on this webpage comes from data returned by the /stats URI.
This page only allows to display informations. Later versions should allow to fetch more informations such as display contact’s custom variable.

Query webpage

This webpage is a frontend to the /spam URI.
It will allow you to send various commands to botmans, and to set filters to have more control over which botmans to query.
Some of these commands have special JS code to enhance their display on the Web app.

Logs webpage

This webpage makes it easier to call the /log/last URI.
It doesn’t allow to set the number of results ATM, but it supports pagination and filters.

API webpage

This webpage is generated by the HTTPd module itself.
Each HTTPd URI handler must declare its documentation to the HTTPd module, allowing it to expose this API through this page.
This can be helpful for lazy people like me.