Skip to content

Commit 03728f1

Browse files
alkalinecoffeealkalinecoffee
committed
feat: Add Networking APIs to spec
1 parent 9ad3187 commit 03728f1

File tree

4 files changed

+872
-2
lines changed

4 files changed

+872
-2
lines changed

‎requirements/specifications/networking/networking.md‎

Lines changed: 273 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,273 @@
1+
# Networking Requirements
2+
3+
Document Status: Proposed Specification
4+
5+
See [Firebolt Requirements Governance](../../governance.md) for more info.
6+
7+
| Contributor | Organization |
8+
| --------------- | -------------- |
9+
| Bart Catrysse | Liberty Global |
10+
| Brian Chow | Sky |
11+
| Jeremy LaCivita | Comcast |
12+
| Joe Martin | Comcast |
13+
14+
## 1. Overview
15+
16+
To provide the best experience to users, content partners want to understand details about a device's network connection, such as the device's connection state, connection type, and that connection's performance capabilities. Content partners also want to be notified of key changes to the device's connection, such as connect/disconnect events or IP changes. This data can be used to gauge how those changes may impact the user's experience and react appropriately.
17+
18+
App partners also have different requirements of what network details are made available to them. For instance, most app partners simply want to know the device's current connection state, type, and be notified of changes to that connection. Other app partners may have more sophisticated needs, requiring access to details on the the configurations of all available network interfaces, including interface MACs, IPs, and wireless connection details.
19+
20+
This information can be used to gracefully handle cases when the device has poor or no network connectivity, provide valuable data into how the user's network performance is impacting their experience, and to unlock more advanced networking features on the device (such as Wake-on-LAN functionality).
21+
22+
These APIs will be surfaced in the Firebolt `Network` module.
23+
24+
### 1.1. User Stories
25+
26+
As an app, I want to...
27+
28+
- Get the device's network connection state and connection type
29+
- Get details on each of the device's interfaces, such as name, MAC address, and IP configuration
30+
- Get details on the wireless connection, such as SSID and signal strength
31+
- Be notified of key changes to the device's network connection, such as connection state, TCP/IP configuration, or wireless signal
32+
33+
## 2. Table of Contents
34+
35+
- [1. Overview](#1-overview)
36+
- [1.1. User Stories](#11-user-stories)
37+
- [2. Table of Contents](#2-table-of-contents)
38+
- [3. Constants, Types, and Schemas](#3-constants-types-and-schemas)
39+
- [3.1. Connection States](#31-connection-states)
40+
- [3.2. Interface Types](#32-interface-types)
41+
- [3.3 Ethernet Standards](#33-ethernet-standards)
42+
- [3.4. Wireless Standards](#34-wireless-standards)
43+
- [4. Network APIs](#4-network-apis)
44+
- [4.1. Connection Status](#41-connection-status)
45+
- [4.2. Interfaces](#42-interfaces)
46+
- [4.3. IP Properties](#43-ip-properties)
47+
- [4.4. Wifi Status](#44-wifi-status)
48+
- [4.5. Wifi Signal Strength Change Event](#45-wifi-signal-strength-change-event)
49+
50+
## 3. Constants, Types, and Schemas
51+
52+
### 3.1. Connection States
53+
54+
The Firebolt `Network` module **MUST** have a `ConnectionState` enumeration:
55+
56+
- `connected`
57+
- `disconnected`
58+
- `unknown`
59+
60+
### 3.2. Interface Types
61+
62+
The Firebolt `Network` module **MUST** have an `InterfaceType` enumeration:
63+
64+
- `ethernet`
65+
- `wifi`
66+
- `other`
67+
- `unknown`
68+
69+
### 3.3 Ethernet Standards
70+
71+
The Firebolt `Network` module **MUST** have an `EthernetStandard` enumeration:
72+
73+
- `Fast Ethernet`
74+
- `Gibabit Ethernet`
75+
- `10 Gigabit Ethernet`
76+
77+
### 3.4. Wireless Standards
78+
79+
The Firebolt `Network` module **MUST** have an `WirelessStandard` enumeration:
80+
81+
| Standard | Description |
82+
| ---------- | ------------- |
83+
| `802.11ac` | |
84+
| `802.11ax` | |
85+
| `802.11be` | |
86+
| `802.11n` | |
87+
| `legacy` | `802.11a/b/g` |
88+
89+
## 4. Network APIs
90+
91+
Apps need to get various details about the device's network configuration and capabilities, such as whether the device is connected to a network, what type of connection is used, and details on the network interfaces available on the device.
92+
93+
Apps also need to be aware of changes to the device's network connection that may occur, either through user-initiated changes or via external factors.
94+
95+
To facilitate this, the `Network` module will surface methods that provide various details of the device's connection to the local network while also allowing apps to subscribe to various events triggered by key changes to the network connection.
96+
97+
### 4.1. Connection Status
98+
99+
The `Network` module **MUST** have a `connectionStatus` method that returns an object describing the device's current network connection status.
100+
101+
This method **MUST** return the following properties:
102+
103+
| Property | Type |
104+
| ----------- | --------- |
105+
| `connected` | `boolean` |
106+
107+
The following properties are **OPTIONAL**:
108+
109+
| Property | Type |
110+
| -------- | ----------------------- |
111+
| `type` | `Network.InterfaceType` |
112+
113+
The result **MUST** be based on the device's preferred/default network interface.
114+
115+
If the device's preferred interface has both an active network connection and valid IP configuration, the `connected` value **MUST** be `true`, otherwise `false` is returned.
116+
117+
If `connected` is `false`, `type` **MUST NOT** be returned.
118+
119+
This method **MUST** have a corresponding `onStatusChanged` event returning the properties listed above to notify listeners when any of the properties have changed and taken effect.
120+
121+
Access to these methods **MUST** require the `use` role of the `xrn:firebolt:capability:network:connectionstatus` capability.
122+
123+
```javascript
124+
Network.connectionStatus()
125+
//> {
126+
//> "connected": true,
127+
//> "type": "wifi"
128+
//> }
129+
```
130+
131+
### 4.2. Interfaces
132+
133+
The `Network` module **MUST** have an `interfaces` method that describes each network interface on the device.
134+
135+
This method **MUST** return an array of objects with the following properties:
136+
137+
| Property | Type | Description |
138+
| ------------------ | -------------------------- | -------------------------------------------------------------------- |
139+
| `connectionState` | `Network.ConnectionState` | |
140+
| `interface` | `string` | Name of the interface (e.g. eth0) |
141+
| `macAddress` | `string` | |
142+
| `preferred` | `boolean` | Whether the interface is the preferred/default interface for routing |
143+
| `subtype` | `Network.InterfaceSubtype` | |
144+
| `type` | `Network.InterfaceType` | |
145+
| `wakeOnLanEnabled` | `boolean` | |
146+
147+
This method **MUST** have a corresponding `onInterfaceChanged` event returning an object with the properties listed above to notify listeners when an interface's properties have changed and taken effect.
148+
149+
Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:network:interfaces` capability.
150+
151+
```javascript
152+
Network.interfaces()
153+
//> [
154+
//> {
155+
//> connectionState: "disconnected"
156+
//> interface: "wifi0"
157+
//> macAddress: "00:00:00:00:00:00"
158+
//> preferred: false
159+
//> subtype: "802.11ac"
160+
//> type: "wifi"
161+
//> wakeOnLanEnabled: true
162+
//> },
163+
//> {
164+
//> connectionState: "connected"
165+
//> interface: "eth0"
166+
//> macAddress: "00:00:00:00:00:00"
167+
//> preferred: true
168+
//> subtype: "Gibabit Ethernet"
169+
//> type: "ethernet"
170+
//> wakeOnLanEnabled: true
171+
//> },
172+
//> ]
173+
```
174+
175+
### 4.3. IP Properties
176+
177+
The `Network` module **MUST** have an `ipProperties` method that returns an object describing the TCP/IP properties of an interface.
178+
179+
This method **MUST** return the following properties:
180+
181+
| Property | Type |
182+
| ------------------ | ---------- |
183+
| `interface` | `string` |
184+
| `ipv4Addresses` | `[]string` |
185+
| `ipv4DNSAddresses` | `[]string` |
186+
| `ipv6Addresses` | `[]string` |
187+
| `ipv6DNSAddresses` | `[]string` |
188+
189+
The method **MUST** require a `string` parameter denoting the interface name on which the result shall be based.
190+
191+
The `ipv4Addresses` and `ipv6Addresses` values **MUST** be presented in CIDR notation.
192+
193+
If an invalid interface name is provided, a `-40404 / Interface not found` JSON-RPC error **MUST** be returned.
194+
195+
This method **MUST** have a corresponding `onIpPropertiesChanged` event returning the properties listed above to notify listeners of changes to an interface's IP properties.
196+
197+
Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:network:ipproperties` capability.
198+
199+
```javascript
200+
Network.ipProperties("eth0")
201+
//> {
202+
//> interface: "eth0"
203+
//> ipv4Addresses: ["192.168.1.100/24"]
204+
//> ipv4DNSAddresses: ["75.75.75.75"]
205+
//> ipv6Addresses: ["2001:db8:abcd:0012::0/64"]
206+
//> ipv6DNSAddresses: ["2001:558:feed::1"]
207+
//> }
208+
```
209+
210+
### 4.4. Wifi Status
211+
212+
The `Network` module **MUST** have a `wifiStatus` method that returns an object describing an interface's connection status to a wireless network.
213+
214+
| Property | Type | Description |
215+
| ----------------- | -------------------------- | --------------------------------------- |
216+
| `connectionState` | `Network.ConnectionState` | |
217+
| `interface` | `string` | |
218+
| `mode` | `Network.WirelessStandard` | Current wireless mode (e.g. `802.11ac`) |
219+
| `signalStrength` | `integer` | Signal strength / RSSI value (in dBm) |
220+
| `ssid` | `string` | Wireless network name |
221+
222+
The method **MUST** support a required `string` parameter denoting the interface name of which the result is based.
223+
224+
If no wireless interface matches the provided name, a `-40404 / Wireless interface not found` JSON-RPC error **MUST** be returned.
225+
226+
If the wireless interface is not connected to a network, the `connectionState` **MUST** return `disconnected`, the `mode` must be `unknown`, `signalStrength` must be `-255` and the `ssid` blank.
227+
228+
Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:network:wifistatus` capability.
229+
230+
```javascript
231+
Network.wifiStatus("wifi0")
232+
//> {
233+
//> connectionState: "connected"
234+
//>  interface: "wifi0"
235+
//> mode: "802.11ac"
236+
//>  signalStrength: -50
237+
//>  ssid: "MyNetwork"
238+
//> }
239+
```
240+
241+
### 4.5. Wifi Signal Strength Change Event
242+
243+
The `Network` module **MUST** have an `onWifiSignalStrengthChange` event to notify listeners of a significant change in the device's wireless connection signal strength.
244+
245+
The method **MUST** support a required `integer` parameter denoting a time interval, in milliseconds, after which the current RSSI is compared to the previous to determine if the signal strength crossed a threshold.
246+
247+
The thresholds may be operator-dependent, but a general guide may be:
248+
249+
| RSSI Threshold (in dBm) | Description |
250+
| ----------------------- | ----------- |
251+
| -50 and higher | Excellent |
252+
| -50 to -60 | Good |
253+
| -60 to -67 | Fair |
254+
| Below -67 | Weak |
255+
256+
This method **MUST** return the following properties:
257+
258+
| Property | Type | Description |
259+
| --------------- | --------- | ------------------------------------- |
260+
| `interface` | `string` | The interface name |
261+
| `currentValue` | `integer` | Current signal strength / RSSI value |
262+
| `previousValue` | `integer` | Previous signal strength / RSSI value |
263+
264+
Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:network:onwifisignalstrengthchange` capability.
265+
266+
```javascript
267+
Network.onWifiSignalStrengthChange(10000)
268+
//> {
269+
//>  interface: "wifi0"
270+
//>  currentValue: -60
271+
//>  previousValue: -50
272+
//> }
273+
```

0 commit comments

Comments
 (0)