HGD-PROTO(7)

NAME
hgd-proto - HGD protocol specification

DESCRIPTION
hgd-proto is a comprehensive guide to the Hackathon Gunther Daemon protocol. The guide is provided so as to encourage the implementation new client programs.

PROTOCOL FUNDAMENTALS
The HGD protocol is a simple mixed text/binary TCP network protocol for use with hgd-netd(1) . The default TCP port for the HGD protocol is 6633.

The majority of communications are performed in a turn based fashion between the server and client. Most communications are line based and terminated with a carriage return and line feed, so as to remain telnet compatible. The only exception to this rule is the ‘q’ command which involves sending binary data over the wire; in this case, communications are precisely bounded in size.

Communications start with the server reporting it's version; the session mostly continues as follows:

1.  Client sends a command and optionally arguments separated by pipe characters.

2.  Server sends either a single- or multi-line reply indicating success/failure and optionally some data.

3.  Goto 1 (unless the connection is terminated for any reason)

Clients must be aware which commands return which kind of reply.

A server reply may contain multiple fields of data, which are separated by the pipe character, ‘|’ .

The first field of every reply always indicates whether the command succeeded or failed ( ‘ok’ and ‘err’ respectively). If a command fails, then the second field is an error code mnemonic which indicates the nature of the failure (for a list of error mnemonics, see net.h). Failed commands always send a single-line reply.

If the client sends three consecutive commands which all return an error, the client connection is assumed to be malicious; an error is sent and the connection is dropped.

Sometimes the server will send an shutdown error (E_SHTDWN) in response to a command; this happens for example, when the server is sent a SIGHUP. Clients should be aware that this response can happen in response to any command.

The maximum size of any line transmitted on the network is 512 bytes.

PROTOCOL COMMANDS
All command arguments are separated by the pipe character, ‘|’ .

Some commands require the connection to be authenticated.

For readability, we put spaces around reply and argument fields in this document. In reality arguments and reply fields have no spaces before and after the pipe separator (unless the spaces are part of actual data).

The command set is as follows:

bye

    -   Arguments: 0

    -   Reply type: single-line

    -   On success returns: ok | <exit_message>

    -   Needs auth: No

    -   Needs admin: No

    Notifies the server that you (the client) are now disconnecting. This allows the server to clean up properly.

encrypt

    -   Arguments: 0

    -   Reply type: single-line

    -   On success returns: ok

    -   Needs auth: No

    -   Needs admin: No

    Notifies the server that all communications from here onward are to encrypted using SSL (TLSv1). Transport of encrypted traffic differs; see SECURE COMMUNICATIONS WITH SSL (TLSv1) .

encrypt?

    -   Arguments: 0

    -   Reply type: single-line

    -   On success returns: ok | <crypto-method>

    -   Needs auth: No

    -   Needs admin: No

    Asks the server if it supports encryption. A <crypto-method> of ‘nocrypto’ indicates the server is incapable of supplying secure communications.

id

    -   Arguments: 0

    -   Reply type: single-line

    -   On success returns: ok | <username> | <permission_mask> | <voted?>

    -   Needs auth: Yes

    -   Needs admin: No

    Requests information about your user account.

    <username> is obvious.

    <permission_mask> is a 16-bit bit-field describing the user's permissions. Please see hgd.h for a list of HGD authentication levels (HGD_AUTH_*).

    <voted?> is a boolean field indicating whether the user has used their vote on the currently playing item.

ls

    -   Arguments: 0

    -   Reply type: multi-line

    -   On success returns: ok | <num-items> ...

    -   Needs auth: No

    -   Needs admin: No

    Requests the playlist. <num_items> indicates how many further lines to expect from the server. Each line returned represents one track in the playlist; the line is of the form:

    <track-id> | <filename> | <artist> | <title> | <user> | <album> | <genre> | <duration> | <bitrate> | <samplerate> | <channels> | <year> | <votesneeded> | <voted?>

    <votesneeded> is the number of votes now needed to skip the song.

    <voted?> applies only to the currently playing song (for now) and is 1 if the currently logged in user has voted, 0 if the user has not, or -1 if the user was not authenticated. If a track is not currently playing, <voted?> is 0.

    In the event of missing tag information, string fields (artist, title, ...) are blank and unknown integer fields (samplerate, duration, ...) are set to 0.

np

    -   Arguments: 0

    -   Reply type: single-line

    -   On success returns: ok | <playing?> [| <track-id> | <filename> | <artist> | <title> | <user> | <album> | <genre> | <duration> | <bitrate> | <samplerate> | <channels> | <year> | <votesneeded> | <voted?>]

    -   Needs auth: No

    -   Needs admin: No

    Get the currently playing item, if any. If <playing?> = 0, then nothing is playing and therefore, no further information is available.

    <votesneeded> is the number of votes now needed to skip the song.

    <voted?> is 1 if the currently logged in user has voted, 0 if the user has not, or -1 if the user was not authenticated.

    In the event of missing tag information, string fields (artist, title, ...) are blank and unknown integer fields (samplerate, duration, ...) are set to 0.

proto

    -   Arguments: 0

    -   Reply type: single-line

    -   On success returns: ok | <proto-major-vers> | <proto-minor-vers>

    -   Needs auth: No

    -   Needs admin: No

    Requests the protocol major and minor versions.

    The HGD developers bump the major version when backward compatibility is broken with the existing protocol version. A client should never attempt to work with a server implementing a differing major HGD protocol version.

    New features that do not break backward compatibility of the existing protocol cause a minor bump. Clients should check that server's minor version is atleast that expected, otherwise there is the possibility that the client requests a feature which does not exist.

q

    -   Arguments: 2 <filename> | <byte-sz>

    -   Reply type: special

    -   Needs auth: Yes

    -   Needs admin: No

    Indicates that a file of size <byte-sz> is to be uploaded. If the file size is within bounds, then the server replies ‘ok | ...’ , which prompts the client to send the file in binary mode. The client should send exactly <byte-sz> bytes. If this goes to plan then the server switches back to text-mode and sends ‘ok’ . The file is inserted into the playlist under the name <filename>.

user

    -   Arguments: 2 <username> | <password>

    -   Reply type: single-line

    -   On success returns: ok

    -   Needs auth: No

    -   Needs admin: No

    Authenticates a user with the current connection.

vo

    -   Arguments: 0

    -   Reply type: single-line

    -   On success returns: ok

    -   Needs auth: Yes

    -   Needs admin: No

    Votes off the currently playing track. It is recommended that clients use the 1-argument variant of this command to avoid race conditions in voting off.

vo (safe variant)

    -   Arguments: 1 <playlist-id>

    -   Reply type: single-line

    -   On success returns: ok

    -   Needs auth: Yes

    -   Needs admin: No

    Votes off the track with the playlist id <playlist-id> if and only if it is now playing.

user-add

    -   Arguments: 2 <username> <password>

    -   Reply type: single-line

    -   On success returns: ok

    -   Needs auth: Yes

    -   Needs admin: Yes

    Adds a user to the system.

user-del

    -   Arguments: 1 <username>

    -   Reply type: single-line

    -   On success returns: ok

    -   Needs auth: Yes

    -   Needs admin: Yes

    Remove a user from the system.

user-list

    -   Arguments: 0

    -   Reply type: multi-line

    -   On success returns: ok | <num-items> ...

    -   Needs auth: Yes

    -   Needs admin: Yes

    List all users on the system. A further <num-items> lines should be expected of the form:

    <user-name> | <permission_mask>

    Each line associates a user name with his/her permissions in the form of a 16-bit bit field. Please see hgd.h for a list of HGD authorisation levels (HGD_AUTH_*).

user-mkadmin

    -   Arguments: 1 <username>

    -   Reply type: single-line

    -   On success returns: ok

    -   Needs auth: Yes

    -   Needs admin: Yes

    Grant a user admin rights (commands marked "Needs admin: Yes").

user-noadmin

    -   Arguments: 0

    -   Reply type: single-line

    -   On success returns: ok

    -   Needs auth: Yes

    -   Needs admin: Yes

    Revoke admin rights from a user.

pause

    -   Arguments: 0

    -   Reply type: single-line

    -   On success returns: ok

    -   Needs auth: Yes

    -   Needs admin: Yes

    Pauses/Un-pauses the current playing track

skip

    -   Arguments: 0

    -   Reply type: singe-line

    -   On success returns: ok

    -   Needs auth: Yes

    -   Needs admin: Yes

    Skip the current playing track.

EXAMPLE SESSION
Here we will demonstrate a simple HGD session. In these examples, a line beginning ‘>’ indicate that the line is sent my the client, whereas a line beginning ‘<’ indicates that it is a reply sent by the server.

1.  Opening the connection and checking protocol version

        < ok|HGD-0.5.0
        > proto
        < ok|17|0

    At this stage the client should check the protocol major and minor versions as described above (see 'proto' command).

2.  Retrieving the playlist

        > ls
        < ok|3
        < 10|10.MX.ogg|Deftones|MX|edd|Around the Fur|Metal|2238|192|44100|2|1997|3|-1
        < 11|01-Dracula_With_Glasses.ogg|Burnt By The Sun|Dracula With Glasses|edd|Soundtrack To The Personal Revolution|Metal|106|192|44100|2|2002|3|0
        < 12|02-Soundtrack_To_The_Worst_Movie_Ever.ogg|Burnt By The Sun|Soundtrack To The Worst Movie Ever|edd|Soundtrack To The Personal Revolution|Metal|152|192|44100|2|2002|3|0

3.  Disconnecting

        > bye
        < ok|Catch you later d00d!

SECURE COMMUNICATIONS WITH SSL (TLSv1)
A typical SSL session should go:

    > encrypt?
    < ok|tls1
    > encrypt
    **ALL traffic should now be encrypted**
    < ok
    > ls
    < ...

SSL messages should be 512 bytes long (padded with NULL if the message is shorter).

If 'encrypt?' returns 'ok|nocrypto', the server does not support SSL. If the server has encryption set to "forced", most commands will not work until an encrypted session is set up ('encrypt?' and 'encrypt' will always work unencrypted).

Currently only TLSv1 is supported and certificates are not yet checked ,so authentication (ie. identity) of the server cannot be trusted.

AUTHORS
-nosplit hgd-proto was written by Edd Barrett <vext01@gmail.com>, and Martin Ellis <ellism88@gmail.com>.

BUGS
Please report bugs in this guide back to use via the github issue tracker.