sul.protocol.externalconsole2 source code

1 /*
2  * This file was automatically generated by sel-utils and
3  * released under the MIT License.
4  * 
5  * License: https://github.com/sel-project/sel-utils/blob/master/LICENSE
6  * Repository: https://github.com/sel-project/sel-utils
7  * Generated from https://github.com/sel-project/sel-utils/blob/master/xml/protocol/externalconsole2.xml
8  */
9 /**
10  * Protocol used to communicate with external sources using a raw TCP protocol or Web
11  * Sockets.
12  * 
13  * <h2>Features</h2>
14  * + Organised remote logs
15  * + Execution of remote commands (if the server allows it)
16  * + Authentication using password hashing (optional)
17  * + Server's resources usage
18  * + Support for the hub-node layout
19  * 
20  * <h2>What's new from protocol 1</h2>
21  * + TCP packet are prefixed with their length
22  * + Command can know when they generate output
23  * 
24  * <h2>Connecting</h2>
25  * 
26  * <h3>Using raw TCP sockets</h3>
27  * The raw TCP protocol, also referred as "classic", uses a packet-oriented TCP connection,
28  * prefixing every packet with its length encoded as a little-endian unsigned 16-bits
29  * integer.
30  * The connection starts with the client sending the string `classic` encoded as UTF-8
31  * to the server, which replies with an AuthCredentials packet and waits for the client
32  * to authenticate.
33  * 
34  * <h3>Using Web Sockets</h3>
35  * The websocket protocol uses json packets instead of binary ones (with the keys in
36  * snake case) and encodes the arrays of bytes (AuthCredentials.payload and Auth.hash)
37  * into strings using base64. The connection is established like every web socket connection
38  * and, if successfull, continues with the AuthCredentials packet sent by the server.
39  * Example of a connection in javascript:
40  * ---
41  * var socket = new WebSocket("example.com:19134");
42  * socket.onmessage = function(event){
43  *    var json = JSON.parse(event.data);
44  *    if(json.hash) console.log("The server requires hash " + json.hash_algorithm);
45  *    else console.log("The server doesn't require hashing");
46  * }
47  * ---
48  * 
49  * <h2>Authenticating</h2>
50  * After receiving the AuthCredentials packet, the external console, if able to perform
51  * authentication, has to send the password or its hash through the Auth packet and
52  * waits for a response, given by the Welcome packet. If the server accepts the external
53  * console the status in the packet will be "accepted", the additional fields of the
54  * Welcome.Accepted packet can be read and the external console can proceed keeping
55  * the connection alive, sending commands, receiving logs and other updates.
56  * 
57  * <h2>Keeping the connection alive</h2>
58  * The server may disconnect the external console after a period of inactivity (which
59  * shouldn't be shorter than 8 seconds). For this reason the external console needs
60  * to send a KeepAlive packet to notify the server that it is still perfectly connected.
61  * 
62  * <h2>Server's logs</h2>
63  * Every time a log is created on the server it sends a ConsoleMessage to the external
64  * console that contains informations about when the log was generated, from whom was
65  * generated and the log itself.
66  * 
67  * <h2>Executing commands</h2>
68  * If the remoteCommand field in the Welcome.Accepted packet is true, the server allows
69  * the execution of commands from the external console. That's done using the Command
70  * packet, which has only one field that is the raw command.
71  */
72 module sul.protocol.externalconsole2;
73 
74 public import sul.protocol.externalconsole2.types;
75 
76 public import sul.protocol.externalconsole2.login;
77 public import sul.protocol.externalconsole2.status;
78 public import sul.protocol.externalconsole2.connected;