sul.protocol.externalconsole1 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/externalconsole1.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>Connecting</h2>
21  * 
22  * <h3>Using raw TCP sockets</h3>
23  * The raw TCP protocol, also referred as "classic", uses a stream-oriented TCP connection.
24  * This means that packets are not prefixed with their length and every packet's length
25  * is fixed or can be retrieved at runtime.
26  * The connection starts with the client sending the string `classic` encoded as UTF-8
27  * to the server, which replies with an AuthCredentials packet and waits for the client
28  * to authenticate.
29  * 
30  * <h3>Using Web Sockets</h3>
31  * The websocket protocol uses json packets instead of binary ones (with the keys in
32  * snake case) and encodes the arrays of bytes (AuthCredentials.payload and Auth.hash)
33  * into strings using base64. The connection is established like every web socket connection
34  * and, if successfull, continues with the AuthCredentials packet sent by the server.
35  * Example of a connection in javascript:
36  * ---
37  * var socket = new WebSocket("example.com:19134");
38  * socket.onmessage = function(event){
39  *    var json = JSON.parse(event.data);
40  *    if(json.hash) console.log("The server requires hash " + json.hash_algorithm);
41  *    else console.log("The server doesn't require hashing");
42  * }
43  * ---
44  * 
45  * <h2>Authenticating</h2>
46  * After receiving the AuthCredentials packet, the external console, if able to perform
47  * authentication, has to send the password or its hash through the Auth packet and
48  * waits for a response, given by the Welcome packet. If the server accepts the external
49  * console the status in the packet will be "accepted", the additional fields of the
50  * Welcome.Accepted packet can be read and the external console can proceed keeping
51  * the connection alive, sending commands, receiving logs and other updates.
52  * 
53  * <h2>Keeping the connection alive</h2>
54  * The server may disconnect the external console after a period of inactivity (which
55  * shouldn't be shorter than 8 seconds). For this reason the external console needs
56  * to send a KeepAlive packet to notify the server that it is still perfectly connected.
57  * 
58  * <h2>Server's logs</h2>
59  * Every time a log is created on the server it sends a ConsoleMessage to the external
60  * console that contains informations about when the log was generated, from whom was
61  * generated and the log itself.
62  * 
63  * <h2>Executing commands</h2>
64  * If the remoteCommand field in the Welcome.Accepted packet is true, the server allows
65  * the execution of commands from the external console. That's done using the Command
66  * packet, which has only one field that is the raw command.
67  */
68 module sul.protocol.externalconsole1;
69 
70 public import sul.protocol.externalconsole1.types;
71 
72 public import sul.protocol.externalconsole1.login;
73 public import sul.protocol.externalconsole1.status;
74 public import sul.protocol.externalconsole1.connected;