MQTT-610 Properly define Virtual Connection

[icraggs]

https://issues.oasis-open.org/browse/MQTT-610

Considered that introducing the new concept was heavy weight. Discuss.

[icraggs]

Simon: What about "logical channel" or "association" or "data channel"

[icraggs]

Ian:

After the discussions we've been having recently around what happens when the retry fails (i.e. reaches the max retry count) and the client has to reconnect, I'm coming around to the idea that "virtual connection" is a pretty good name for the concept. It also aligns with the "connection" concept and terminology in MQTT.

[icraggs]

Ian:

It seemed difficult to define Virtual Connection without refactoring the rest of the Terminology section. I based it on the MQTT 5 Terminology section, only diverging where necessary. So here is my proposal:

Datagram:

An independent, self-contained sequence of bytes.

Transport Layer:

The underlying network which provides the means to send datagrams from one Network Address to another.

The arrival of a datagram is not guaranteed, but the contents of any datagram which does arrive at its destination must be correct.

Network Address:

A label provided by the Transport Layer to identify network endpoints.

To receive datagrams, an MQTT-SN Client or Server must listen to a Network Address.

Unicast Address:

A Network Address on which one application can listen.

Broadcast Address:

A Network Address on which more than one application can listen.

Informative:

Includes multicast addresses.

Virtual Connection:

An MQTT-SN construct corresponding to the network connection in MQTT. It:

links a Unicast Address to an MQTT-SN endpoint
is created with a CONNECT packet
is deleted by a retry timeout or DISCONNECT packet
is required for any MQTT-SN packet to be sent between MQTT-SN clients and servers, except:
CONNECT, which creates a Virtual Connection
PUBLISH WITHOUT SESSION

Application Message:

The data carried by the MQTT-SN protocol across the network for the application. When an Application Message is transported by MQTT-SN it contains payload data, a Quality of Service (QoS), and a Topic Name.

Client:

A program or device that uses MQTT-SN. A Client:

opens a Virtual Connection to a Server.
publishes Application Messages that other Clients might be interested in.
subscribes to request Application Messages that it is interested in receiving.
unsubscribes to remove a request for Application Messages.
closes the Virtual Connection to the Server.

and/or:

publishes Application Messages to a Broadcast Address.

and/or:

accepts Application Messages from a Broadcast Address.

Server:

A program or device that acts as an intermediary between Clients which publish Application Messages and Clients which have made Subscriptions.

Also known as a Gateway, GW for short.

A Server:

accepts CONNECT requests from Clients.
accepts Application Messages published by Clients.
processes Subscribe and Unsubscribe requests from Clients.
forwards Application Messages that match Client Subscriptions.
closes the Network Connection from the Client.

and/or

accepts messages from a Broadcast Address.

and/or

establishes an MQTT session with an MQTT Server.
accepts Application Messages from the MQTT Server and forwards some or all to MQTT-SN Clients.
accepts Application Messages from MQTT-SN Clients and forwards some or all to the MQTT Server.

and/or

opens an MQTT Network Connection to an MQTT Server for every MQTT-SN CONNECT request
forwards equivalent MQTT requests to the MQTT Server for each MQTT-SN request received
forwards equivalent MQTT-SN requests to the MQTT-SN Client for each MQTT request received
closes the MQTT Network Connection when the Virtual Connection is closed

MQTT Server:

A program or device that acts as an intermediary between MQTT Clients which publish Application Messages and MQTT Clients which have made Subscriptions.

Also known as a Broker.

An MQTT Server:

accepts Network Connections from MQTT Clients.
accepts Application Messages published by MQTT Clients.
processes Subscribe and Unsubscribe requests from MQTT Clients.
forwards Application Messages that match MQTT Client Subscriptions.
closes the Network Connection from the MQTT Client.

Session:

A stateful interaction between a Client and a Gateway. Some Sessions last only as long as the Virtual Connection, others can span multiple consecutive Virtual Connections between a Client and a Gateway.

Subscription:

A Subscription comprises a Topic Filter and a maximum QoS. A Subscription is associated with a single Session. A Session can contain more than one Subscription. Each Subscription within a Session has a different Topic Filter.

Wildcard Subscription:

A Wildcard Subscription is a Subscription with a Topic Filter containing one or more wildcard characters. This allows the subscription to match more than one Topic Name. Refer to[ section ??? |https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Topic_Names_and]for a description of wildcard characters in a Topic Filter.

Topic Name:

The label attached to an Application Message which is matched against the Subscriptions known to the Server.

Topic Alias:

An integer value that is used instead of the Topic Name to reduce packet size.

Topic Filter:

An expression contained in a Subscription to indicate an interest in one or more topics. A Topic Filter can include wildcard characters.

MQTT-SN Control Packet:

A packet of information that is sent to a Network Address.

Malformed Packet:

A Control Packet that cannot be parsed according to this specification. Refer to section ??? for information about error handling.

Protocol Error:

An error that is detected after the packet has been parsed and found to contain data that is not allowed by the protocol or is inconsistent with the state of the Client or Server. Refer to section ??? for information about error handling.

Will Message:

An Application Message which is published by the Server after the Virtual Connection is closed in cases where the Virtual Connection is not closed normally. Refer to section ??? for information about Will Messages.

Disallowed Unicode code point:

The set of Unicode Control Codes and Unicode Noncharacters which should not be included in a UTF-8 Encoded String. Refer to section ??? for more information about the Disallowed Unicode code points.

Wireless Sensor Network:

Spatially dispersed and dedicated sensors that monitor and record the physical conditions of the environment and forward the collected data to a central location.

Also known as WSN, for short.

[icraggs]

Davide made the comment that Transport Layer might be confused with the OSI term.

I suggest Underlying Network, or Base Network. Any others?

[simon622]

Network Address should be used. Underlying network should be used Broadcast Address should be used - with small description Unicast Address should be used - with small description

[icraggs]

Tracking in Jira again.

[sthagen]

At https://issues.oasis-open.org/browse/MQTT-610