CRecordTcpCreateClient

This nano service (im Namespace SYSTEM) is run by the TCP plugin and creates a TCP client that can then be used for messaging. There is an automatic link with the layer above (plugin NY_Network).

{
  "id": "82c787b3-4541-4928-bff4-5862291a837e",
  "name": "TCP_CREATE_CLIENT",
  "isNanoService": "true",
  "type": "REQUEST",
  "hasOtherSlots": "false",
  "description": "Create and start a TCP client.",
  "namespaces": "SYSTEM",
  "slots": [
    {
      "key": "1",
      "name": "ID",
      "direction": "REQUEST",
      "presenceConstraint": "MANDATORY",
      "type": "UUID",
      "description": "The connection ID (useful for tracking)."
    },
    {
      "key": "2",
      "name": "HOST",
      "direction": "REQUEST",
      "presenceConstraint": "MANDATORY",
      "type": "STRING",
      "description": "The address (IP or Host) to connect."
    },
    {
      "key": "3",
      "name": "PORT",
      "direction": "REQUEST",
      "presenceConstraint": "MANDATORY",
      "type": "INT",
      "description": "The port of the TCP connection."
    },
    {
      "key": "4",
      "name": "TLS_ENABLED",
      "direction": "REQUEST",
      "presenceConstraint": "OPTIONAL",
      "type": "BOOLEAN",
      "description": "True if this is a TLS socket. Default: false"
    },
    {
      "key": "5",
      "name": "TLS_PROTOCOLS",
      "direction": "REQUEST",
      "presenceConstraint": "OPTIONAL",
      "type": "STRING",
      "description": "The TLS protocol. Default: TLSv1.3"
    },
    {
      "key": "6",
      "name": "TLS_CIPHER_SUITES",
      "direction": "REQUEST",
      "presenceConstraint": "OPTIONAL",
      "type": "STRING",
      "description": "The TLS cipher suite. Default: TLS_AES_128_GCM_SHA256"
    },
    {
      "key": "7",
      "name": "INPUT_BUFFER_SIZE",
      "direction": "REQUEST",
      "presenceConstraint": "OPTIONAL",
      "type": "INT",
      "description": "The input buffer size. Default: 270000"
    },
    {
      "key": "8",
      "name": "RETRY_TIMEOUT",
      "direction": "REQUEST",
      "presenceConstraint": "MANDATORY",
      "type": "LONG",
      "description": "The retry timeout.\nIf the connection could not be established, a retry will be performed after this time in milliseconds.\nA timeout of 0 means no retry."
    },
    {
      "key": "9",
      "name": "FAIL_ON_FIRST_CONNECT",
      "direction": "REQUEST",
      "presenceConstraint": "OPTIONAL",
      "type": "BOOLEAN",
      "description": "Default: false.\nFail if the first connection attempt couldn't be established.\nFurther connection attempts after an interruption of the connection are not affected by this, see argument RETRY_TIMEOUT."
    },
    {
      "key": "10",
      "name": "WANT_UPDATE_ON_RETRY",
      "direction": "REQUEST",
      "presenceConstraint": "OPTIONAL",
      "type": "BOOLEAN",
      "description": "Default: false.\nWant an update message on the beginning of each retry waiting period.\nSee TCP_CREATE_CLIENT_RETRY"
    }
  ]
}

Slot Description

Key	Name	Direction	Presence Constraint	Type	Description
1	ID	REQUEST	MANDATORY	UUID	The connection ID (useful for tracking).
2	HOST	REQUEST	MANDATORY	STRING	The address (IP or Host) to connect.
3	PORT	REQUEST	MANDATORY	INT	The port of the TCP connection.
4	TLS_ENABLED	REQUEST	OPTIONAL	BOOLEAN	True if this is a TLS socket. Default: false.
5	TLS_PROTOCOLS	REQUEST	OPTIONAL	STRING	The TLS protocol. Default: TLSv1.3
6	TLS_CIPHER_SUITES	REQUEST	OPTIONAL	STRING	The TLS cipher suite. Default: TLS_AES_128_GCM_SHA256
7	INPUT_BUFFER_SIZE	REQUEST	OPTIONAL	INT	The input buffer size. Default: 270000
8	RETRY_TIMEOUT	REQUEST	MANDATORY	LONG	The retry timeout. If the connection could not be established, a retry will be performed after this time in milliseconds. A timeout of 0 means no retry.
9	FAIL_ON_FIRST_CONNECT	REQUEST	OPTIONAL	BOOLEAN	Default: false. Fail if the first connection attempt couldn't be established. Further connection attempts after an interruption of the connection are not affected by this. Note the argument RETRY_TIMEOUT.
10	WANT_UPDATE_ON_RETRY	REQUEST	OPTIONAL	BOOLEAN	Default: false. Want an update message at the beginning of each retry waiting period. Note TCP_CREATE_CLIENT_RETRY.

In addition to the host and port, an ID must be specified. This is an arbitrary UUID and is only used to reference this client.

The other specifications are optional.

Retry timeout

For clients, you can specify a retry timeout in milliseconds. If the timeout is greater than 0 and a connection attempt fails, the client will try to reach the server again after this timeout. This also allows you to reboot individual nodes, since the nodes reconnect immediately and the network is functional again.

Fail on first connect

If the flag FAIL_ON_FIRST_CONNECT is set, the client will not retry to reach the server in case of an error (server unreachable, protocol error on encryption). A possibly specified retry timeout (see above) becomes active in this case only if a connection has already existed once.

Want update on retry

If the flag WANT_UPDATE_ON_RETRY is set, the owner (sender of the message) will receive another message when the client tries to reactivate a broken connection. In this case the CRecordTcpCreateClientRetry message is sent to the owner.

TLS

To create an encrypted connection using TLS, see here: Requirement for a TLS connection.

Record Usage

In nyssr.net, we typically don't exchange interfaces between projects. Instead, we use platform-independent Records to describe message formats.

One or more descriptions of these Records are stored in the JSON or XML format as record.json or record.xml within a directory. The Record Generator, an included Swing tool, generates helper classes from these files. These classes can then be used to type-safely write or read messages.