Network Protocol Tutorial
Total Page:16
File Type:pdf, Size:1020Kb
Network Protocol Tutorial Target: Lightstreamer Generic Client Protocol v. 6.0.1 Last updated: 04/02/2015 Table of contents 1 INTRODUCTION................................................................................................................4 2 GENERAL WORKFLOW.........................................................................................................5 2.1 HTTP Requests................................................................................................5 2.1.1 HTTP vs. HTTPS...............................................................................................5 2.1.2 GET method vs. POST method..........................................................................5 2.1.3 Lightstreamer Server behind a Load Balancer.....................................................5 2.2 Subscriptions and unsubscriptions.....................................................................6 2.3 Stream Connection, Control Connections and Polling connections........................6 2.4 Data reception workflows.................................................................................7 2.4.1 Basic workflow.................................................................................................7 2.4.2 Double subscription..........................................................................................8 2.4.3 Field schema change........................................................................................9 2.5 Content-Length management..........................................................................10 2.6 External Snapshots.........................................................................................12 3 SUBSCRIPTION MANAGEMENT..............................................................................................15 3.1 Basic concepts...............................................................................................15 4 THE TEXT MODE PROTOCOL...............................................................................................16 4.1 Creating the Stream Connection......................................................................16 4.2 Binding to an existing Session.........................................................................18 4.3 Control connections........................................................................................20 4.3.1 Subscription Control Connections.....................................................................20 4.3.2 Item Groups and Field Schemas......................................................................22 4.3.3 Subscription reconfiguration Control Connections.............................................23 4.3.4 Session constraints Control Connections..........................................................23 4.3.5 Asynchronous request for session rebind Control Connections...........................24 4.3.6 Session asynchronous destroy Control Connections..........................................25 4.3.7 Batching of Control Requests..........................................................................25 4.4 Sending Messages..........................................................................................26 4.4.1 Synchronous version.......................................................................................26 4.4.2 Asynchronous version.....................................................................................26 4.5 Push Contents................................................................................................28 4.5.1 Update messages...........................................................................................28 4.5.2 End-of-Snapshot messages.............................................................................30 4.5.3 Overflow messages........................................................................................30 4.5.4 Asynchronous Send Message outcome messages.............................................30 4.5.5 Probe messages.............................................................................................31 4.5.6 End messages................................................................................................31 4.5.7 Loop messages..............................................................................................32 - 2 - 4.5.8 Push error messages......................................................................................32 5 TESTS AND EXAMPLES......................................................................................................33 5.1 Test environment...........................................................................................33 5.2 Table (i.e. Subscription) management..............................................................34 5.2.1 Basic workflow...............................................................................................35 5.2.2 Double subscription........................................................................................36 5.2.3 Field schema change......................................................................................38 5.2.4 Snapshot synchronization...............................................................................40 5.2.5 Multiple subscriptions of the same item...........................................................42 - 3 - 1 Introduction If you use a Client Library (e.g. SDK for JavaScript Clients, SDK for .NET Clients, etc.) to develop a Lightstreamer Client, then you don’t need to read this document. This document specifies the Lightstreamer network protocol that can be used to implement Lightstreamer Client at socket level. The described protocol is supported by the current version of Lightstreamer Server; see the SDK compatibility notes. Any older versions of the protocol are still supported; they should be considered as deprecated and are not included here. In order to receive realtime updates from Lightstreamer Server, a Lightstreamer Client should open an HTTP/HTTPS connection (called stream connection), through which it authenticates and waits for incoming realtime updates. The Lightstreamer Client could eventually open other HTTP/HTTPS connections (called control connections) through which it sends commands to the server in order to manage the contents of the stream connection (see section 2.3, Stream Connection, Control Connections). Basically, there are two different communication protocols that a client can use in order to communicate with Lightstreamer Server: The JavaScript mode, where realtime updates are packed into JavaScript commands (used by HTML Web clients and, in general, clients based on the JavaScript Client Library). The Text mode, where realtime updates are packed in a simple pipe-separated text protocol (usually used by application clients). The topic of this document is the Lightstreamer Server Text mode protocol. It will also be explained the general data subscription/unsubscription/reception workflow. - 4 - 2 General workflow In this chapter we will provide a quick overview of the general Lightstreamer Server behaviour, in order to give the reader the basic understanding of how the server works. 2.1 HTTP Requests All the requests that a client sends to Lightstreamer Server use the HTTP protocol over TCP. Lightstreamer Server also supports HTTP over SSL connections (HTTPS connections). There are two different HTTP methods that can be used for the requests to the server: the GET method and the POST method. In a production environment, a cluster of Lightstreamer Server can be placed behind a Load Balancer. All these cases will be discussed in this section. 2.1.1 HTTP vs. HTTPS The client developer has to choose between when normal HTTP connections should be used and when to use secure HTTP (HTTPS) connections; it is recommended to use the following policy: HTTPS should be used for stream connections when realtime data should be encrypted or the user authentication has critical security issues, because on these kinds of connections all user identification data (from the client to the server) and market data (from the server to the client) are sent. Otherwise HTTP is suitable for stream connections. HTTP should be used for control connections, because with these connections no sensitive data are sent. In this case it is possible to avoid the SSL server-side and client-side encryption and consequently optimize system performance. 2.1.2 GET method vs. POST method There are two different HTTP methods that can be used for requests: the GET method and the POST method. As a general rule, requests to Lightstreamer Server cause side effects on the Server behaviour, thus, according to HTTP specifications, they should always be issued through the POST method. This also avoids any issue with querystring length limits and is compliant with the Web Services standards. For testing purposes, however, it may be far easier to use the GET method. For instance, this would allow you to issue manual requests through the “telnet” utility without being annoyed by the content-length requirements. This would also allow you to issue manual requests through a browser address bar. Using the GET method, though not strictly compliant with HTTP specifications, will, in general, work as well. Just ensure that the user agent and any intermediate node don't try to leverage the properties of the HTTP GET method to issue duplicated requests, for any reason. 2.1.3 Lightstreamer Server behind a Load Balancer Every Lightstreamer Server maintains a