Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Restructure relay API messages #6753

Merged
merged 2 commits into from
Dec 11, 2023
Merged

Restructure relay API messages #6753

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d6c4cff
all: Extract serving relay forwarding limits message
adriansmares Nov 23, 2023
3e607c7
all: Extract relay uplink forwarding rule message
adriansmares Nov 23, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 27 additions & 27 deletions api/ttn/lorawan/v3/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -276,11 +276,11 @@
- [Message `MACState.UplinkMessage.RxMetadata.RelayMetadata`](#ttn.lorawan.v3.MACState.UplinkMessage.RxMetadata.RelayMetadata)
- [Message `MACState.UplinkMessage.TxSettings`](#ttn.lorawan.v3.MACState.UplinkMessage.TxSettings)
- [Message `RelayParameters`](#ttn.lorawan.v3.RelayParameters)
- [Message `RelayUplinkForwardingRule`](#ttn.lorawan.v3.RelayUplinkForwardingRule)
- [Message `ResetAndGetEndDeviceRequest`](#ttn.lorawan.v3.ResetAndGetEndDeviceRequest)
- [Message `ServedRelayParameters`](#ttn.lorawan.v3.ServedRelayParameters)
- [Message `ServingRelayForwardingLimits`](#ttn.lorawan.v3.ServingRelayForwardingLimits)
- [Message `ServingRelayParameters`](#ttn.lorawan.v3.ServingRelayParameters)
- [Message `ServingRelayParameters.ForwardingLimits`](#ttn.lorawan.v3.ServingRelayParameters.ForwardingLimits)
- [Message `ServingRelayParameters.UplinkForwardingRule`](#ttn.lorawan.v3.ServingRelayParameters.UplinkForwardingRule)
- [Message `Session`](#ttn.lorawan.v3.Session)
- [Message `SetEndDeviceRequest`](#ttn.lorawan.v3.SetEndDeviceRequest)
- [Message `UpdateEndDeviceRequest`](#ttn.lorawan.v3.UpdateEndDeviceRequest)
Expand Down Expand Up @@ -4373,6 +4373,21 @@ This is used internally by the Network Server.
| `serving` | [`ServingRelayParameters`](#ttn.lorawan.v3.ServingRelayParameters) | | Parameters related to a relay which is serving end devices. |
| `served` | [`ServedRelayParameters`](#ttn.lorawan.v3.ServedRelayParameters) | | Parameters related to an end device served by a relay. |

### <a name="ttn.lorawan.v3.RelayUplinkForwardingRule">Message `RelayUplinkForwardingRule`</a>

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| `limits` | [`RelayUplinkForwardLimits`](#ttn.lorawan.v3.RelayUplinkForwardLimits) | | Bucket configuration for the served end device. If unset, no individual limits will apply to the end device, but the relay global limitations will apply. |
| `last_w_f_cnt` | [`uint32`](#uint32) | | Last wake on radio frame counter used by the served end device. |
| `device_id` | [`string`](#string) | | End device identifier of the served end device. |
| `session_key_id` | [`bytes`](#bytes) | | Session key ID of the session keys used to derive the root relay session key. |

#### Field Rules

| Field | Validations |
| ----- | ----------- |
| `device_id` | <p>`string.max_len`: `36`</p><p>`string.pattern`: `^[a-z0-9](?:[-]?[a-z0-9]){2,}$`</p> |

### <a name="ttn.lorawan.v3.ResetAndGetEndDeviceRequest">Message `ResetAndGetEndDeviceRequest`</a>

| Field | Type | Label | Description |
Expand Down Expand Up @@ -4404,25 +4419,7 @@ This is used internally by the Network Server.
| `backoff` | <p>`uint32.lte`: `63`</p> |
| `serving_device_id` | <p>`string.max_len`: `36`</p><p>`string.pattern`: `^[a-z0-9](?:[-]?[a-z0-9]){2,}$`</p> |

### <a name="ttn.lorawan.v3.ServingRelayParameters">Message `ServingRelayParameters`</a>

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| `second_channel` | [`RelaySecondChannel`](#ttn.lorawan.v3.RelaySecondChannel) | | Second wake on radio channel configuration. |
| `default_channel_index` | [`uint32`](#uint32) | | Index of the default wake on radio channel. |
| `cad_periodicity` | [`RelayCADPeriodicity`](#ttn.lorawan.v3.RelayCADPeriodicity) | | Channel activity detection periodicity. |
| `uplink_forwarding_rules` | [`ServingRelayParameters.UplinkForwardingRule`](#ttn.lorawan.v3.ServingRelayParameters.UplinkForwardingRule) | repeated | Configured uplink forwarding rules. |
| `limits` | [`ServingRelayParameters.ForwardingLimits`](#ttn.lorawan.v3.ServingRelayParameters.ForwardingLimits) | | Configured forwarding limits. If unset, the default value from Network Server configuration will be used. |

#### Field Rules

| Field | Validations |
| ----- | ----------- |
| `default_channel_index` | <p>`uint32.lte`: `255`</p> |
| `cad_periodicity` | <p>`enum.defined_only`: `true`</p> |
| `uplink_forwarding_rules` | <p>`repeated.max_items`: `16`</p> |

### <a name="ttn.lorawan.v3.ServingRelayParameters.ForwardingLimits">Message `ServingRelayParameters.ForwardingLimits`</a>
### <a name="ttn.lorawan.v3.ServingRelayForwardingLimits">Message `ServingRelayForwardingLimits`</a>

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
Expand All @@ -4432,20 +4429,23 @@ This is used internally by the Network Server.
| `uplink_messages` | [`RelayForwardLimits`](#ttn.lorawan.v3.RelayForwardLimits) | | Bucket configuration for uplink messages across all served end devices. If unset, no individual limits will apply to uplink messages across all served end devices, but the relay overall limitations will still apply. |
| `overall` | [`RelayForwardLimits`](#ttn.lorawan.v3.RelayForwardLimits) | | Bucket configuration for all relay messages. If unset, no overall limits will apply to the relay, but individual limitations will still apply. |

### <a name="ttn.lorawan.v3.ServingRelayParameters.UplinkForwardingRule">Message `ServingRelayParameters.UplinkForwardingRule`</a>
### <a name="ttn.lorawan.v3.ServingRelayParameters">Message `ServingRelayParameters`</a>

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| `limits` | [`RelayUplinkForwardLimits`](#ttn.lorawan.v3.RelayUplinkForwardLimits) | | Bucket configuration for the served end device. If unset, no individual limits will apply to the end device, but the relay global limitations will apply. |
| `last_w_f_cnt` | [`uint32`](#uint32) | | Last wake on radio frame counter used by the served end device. |
| `device_id` | [`string`](#string) | | End device identifier of the served end device. |
| `session_key_id` | [`bytes`](#bytes) | | Session key ID of the session keys used to derive the root relay session key. |
| `second_channel` | [`RelaySecondChannel`](#ttn.lorawan.v3.RelaySecondChannel) | | Second wake on radio channel configuration. |
| `default_channel_index` | [`uint32`](#uint32) | | Index of the default wake on radio channel. |
| `cad_periodicity` | [`RelayCADPeriodicity`](#ttn.lorawan.v3.RelayCADPeriodicity) | | Channel activity detection periodicity. |
| `uplink_forwarding_rules` | [`RelayUplinkForwardingRule`](#ttn.lorawan.v3.RelayUplinkForwardingRule) | repeated | Configured uplink forwarding rules. |
| `limits` | [`ServingRelayForwardingLimits`](#ttn.lorawan.v3.ServingRelayForwardingLimits) | | Configured forwarding limits. If unset, the default value from Network Server configuration will be used. |

#### Field Rules

| Field | Validations |
| ----- | ----------- |
| `device_id` | <p>`string.max_len`: `36`</p><p>`string.pattern`: `^[a-z0-9](?:[-]?[a-z0-9]){2,}$`</p> |
| `default_channel_index` | <p>`uint32.lte`: `255`</p> |
| `cad_periodicity` | <p>`enum.defined_only`: `true`</p> |
| `uplink_forwarding_rules` | <p>`repeated.max_items`: `16`</p> |

### <a name="ttn.lorawan.v3.Session">Message `Session`</a>

Expand Down
100 changes: 50 additions & 50 deletions api/ttn/lorawan/v3/api.swagger.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19323,54 +19323,6 @@
"default": "ENABLED",
"description": " - ENABLED: No restrictions are in place.\n - WARNING: Warnings are being emitted that the provider will be deprecated in the future.\n - DISABLED: New integrations cannot be set up, and old ones do not start."
},
"ServingRelayParametersForwardingLimits": {
"type": "object",
"properties": {
"reset_behavior": {
"$ref": "#/definitions/v3RelayResetLimitCounter",
"description": "Reset behavior of the buckets upon limit update."
},
"join_requests": {
"$ref": "#/definitions/v3RelayForwardLimits",
"description": "Bucket configuration for join requests.\nIf unset, no individual limits will apply to join requests, but the relay overall limitations will apply."
},
"notifications": {
"$ref": "#/definitions/v3RelayForwardLimits",
"description": "Bucket configuration for unknown device notifications.\nIf unset, no individual limits will apply to unknown end device notifications, but the relay overall\nlimitations will still apply."
},
"uplink_messages": {
"$ref": "#/definitions/v3RelayForwardLimits",
"description": "Bucket configuration for uplink messages across all served end devices.\nIf unset, no individual limits will apply to uplink messages across all served end devices, but the relay\noverall limitations will still apply."
},
"overall": {
"$ref": "#/definitions/v3RelayForwardLimits",
"description": "Bucket configuration for all relay messages.\nIf unset, no overall limits will apply to the relay, but individual limitations will still apply."
}
}
},
"ServingRelayParametersUplinkForwardingRule": {
"type": "object",
"properties": {
"limits": {
"$ref": "#/definitions/v3RelayUplinkForwardLimits",
"description": "Bucket configuration for the served end device.\nIf unset, no individual limits will apply to the end device, but the relay global limitations will apply."
},
"last_w_f_cnt": {
"type": "integer",
"format": "int64",
"description": "Last wake on radio frame counter used by the served end device."
},
"device_id": {
"type": "string",
"description": "End device identifier of the served end device."
},
"session_key_id": {
"type": "string",
"format": "byte",
"description": "Session key ID of the session keys used to derive the root relay session key."
}
}
},
"TxAcknowledgmentResult": {
"type": "string",
"enum": [
Expand Down Expand Up @@ -25693,6 +25645,29 @@
}
}
},
"v3RelayUplinkForwardingRule": {
"type": "object",
"properties": {
"limits": {
"$ref": "#/definitions/v3RelayUplinkForwardLimits",
"description": "Bucket configuration for the served end device.\nIf unset, no individual limits will apply to the end device, but the relay global limitations will apply."
},
"last_w_f_cnt": {
"type": "integer",
"format": "int64",
"description": "Last wake on radio frame counter used by the served end device."
},
"device_id": {
"type": "string",
"description": "End device identifier of the served end device."
},
"session_key_id": {
"type": "string",
"format": "byte",
"description": "Session key ID of the session keys used to derive the root relay session key."
}
}
},
"v3Right": {
"type": "string",
"enum": [
Expand Down Expand Up @@ -25909,6 +25884,31 @@
}
}
},
"v3ServingRelayForwardingLimits": {
"type": "object",
"properties": {
"reset_behavior": {
"$ref": "#/definitions/v3RelayResetLimitCounter",
"description": "Reset behavior of the buckets upon limit update."
},
"join_requests": {
"$ref": "#/definitions/v3RelayForwardLimits",
"description": "Bucket configuration for join requests.\nIf unset, no individual limits will apply to join requests, but the relay overall limitations will apply."
},
"notifications": {
"$ref": "#/definitions/v3RelayForwardLimits",
"description": "Bucket configuration for unknown device notifications.\nIf unset, no individual limits will apply to unknown end device notifications, but the relay overall\nlimitations will still apply."
},
"uplink_messages": {
"$ref": "#/definitions/v3RelayForwardLimits",
"description": "Bucket configuration for uplink messages across all served end devices.\nIf unset, no individual limits will apply to uplink messages across all served end devices, but the relay\noverall limitations will still apply."
},
"overall": {
"$ref": "#/definitions/v3RelayForwardLimits",
"description": "Bucket configuration for all relay messages.\nIf unset, no overall limits will apply to the relay, but individual limitations will still apply."
}
}
},
"v3ServingRelayParameters": {
"type": "object",
"properties": {
Expand All @@ -25929,12 +25929,12 @@
"type": "array",
"items": {
"type": "object",
"$ref": "#/definitions/ServingRelayParametersUplinkForwardingRule"
"$ref": "#/definitions/v3RelayUplinkForwardingRule"
},
"description": "Configured uplink forwarding rules."
},
"limits": {
"$ref": "#/definitions/ServingRelayParametersForwardingLimits",
"$ref": "#/definitions/v3ServingRelayForwardingLimits",
"description": "Configured forwarding limits.\nIf unset, the default value from Network Server configuration will be used."
}
}
Expand Down
84 changes: 48 additions & 36 deletions api/ttn/lorawan/v3/end_device.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,52 @@ message BoolValue {
bool value = 1;
}

message ServingRelayForwardingLimits {
option (thethings.flags.message) = {
select: true,
set: true
};

// Reset behavior of the buckets upon limit update.
RelayResetLimitCounter reset_behavior = 1;
// Bucket configuration for join requests.
// If unset, no individual limits will apply to join requests, but the relay overall limitations will apply.
RelayForwardLimits join_requests = 2;
// Bucket configuration for unknown device notifications.
// If unset, no individual limits will apply to unknown end device notifications, but the relay overall
// limitations will still apply.
RelayForwardLimits notifications = 3;
// Bucket configuration for uplink messages across all served end devices.
// If unset, no individual limits will apply to uplink messages across all served end devices, but the relay
// overall limitations will still apply.
RelayForwardLimits uplink_messages = 4;
// Bucket configuration for all relay messages.
// If unset, no overall limits will apply to the relay, but individual limitations will still apply.
RelayForwardLimits overall = 5;
}

message RelayUplinkForwardingRule {
option (thethings.flags.message) = {
select: true,
set: true
};

// Bucket configuration for the served end device.
// If unset, no individual limits will apply to the end device, but the relay global limitations will apply.
RelayUplinkForwardLimits limits = 1;
// Last wake on radio frame counter used by the served end device.
uint32 last_w_f_cnt = 2;

// End device identifier of the served end device.
string device_id = 3 [(validate.rules).string = {
pattern: "^[a-z0-9](?:[-]?[a-z0-9]){2,}$",
max_len: 36,
ignore_empty: true
}];
// Session key ID of the session keys used to derive the root relay session key.
bytes session_key_id = 4;
}

message ServingRelayParameters {
option (thethings.flags.message) = {
select: true,
Expand All @@ -100,45 +146,11 @@ message ServingRelayParameters {
uint32 default_channel_index = 2 [(validate.rules).uint32.lte = 255];
// Channel activity detection periodicity.
RelayCADPeriodicity cad_periodicity = 3 [(validate.rules).enum.defined_only = true];
message UplinkForwardingRule {
// Bucket configuration for the served end device.
// If unset, no individual limits will apply to the end device, but the relay global limitations will apply.
RelayUplinkForwardLimits limits = 1;
// Last wake on radio frame counter used by the served end device.
uint32 last_w_f_cnt = 2;

// End device identifier of the served end device.
string device_id = 3 [(validate.rules).string = {
pattern: "^[a-z0-9](?:[-]?[a-z0-9]){2,}$",
max_len: 36,
ignore_empty: true
}];
// Session key ID of the session keys used to derive the root relay session key.
bytes session_key_id = 4;
}
// Configured uplink forwarding rules.
repeated UplinkForwardingRule uplink_forwarding_rules = 4 [(validate.rules).repeated.max_items = 16];
message ForwardingLimits {
// Reset behavior of the buckets upon limit update.
RelayResetLimitCounter reset_behavior = 1;
// Bucket configuration for join requests.
// If unset, no individual limits will apply to join requests, but the relay overall limitations will apply.
RelayForwardLimits join_requests = 2;
// Bucket configuration for unknown device notifications.
// If unset, no individual limits will apply to unknown end device notifications, but the relay overall
// limitations will still apply.
RelayForwardLimits notifications = 3;
// Bucket configuration for uplink messages across all served end devices.
// If unset, no individual limits will apply to uplink messages across all served end devices, but the relay
// overall limitations will still apply.
RelayForwardLimits uplink_messages = 4;
// Bucket configuration for all relay messages.
// If unset, no overall limits will apply to the relay, but individual limitations will still apply.
RelayForwardLimits overall = 5;
}
repeated RelayUplinkForwardingRule uplink_forwarding_rules = 4 [(validate.rules).repeated.max_items = 16];
// Configured forwarding limits.
// If unset, the default value from Network Server configuration will be used.
ForwardingLimits limits = 5;
ServingRelayForwardingLimits limits = 5;
}

message ServedRelayParameters {
Expand Down
2 changes: 1 addition & 1 deletion pkg/networkserver/mac/relay.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ func relayForwardLimitsFields(limits *ttnpb.RelayForwardLimits, prefix string) [
}
}

func relayConfigureForwardLimitsFields(limits *ttnpb.ServingRelayParameters_ForwardingLimits) log.Fielder {
func relayConfigureForwardLimitsFields(limits *ttnpb.ServingRelayForwardingLimits) log.Fielder {
if limits == nil {
return log.Fields()
}
Expand Down
4 changes: 2 additions & 2 deletions pkg/networkserver/mac/relay_configure_fwd_limit.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ import (
var (
// defaultRelayForwardingLimits is the default relay forward limits, based on the contents of the
// relay specification.
defaultRelayForwardingLimits = &ttnpb.ServingRelayParameters_ForwardingLimits{
defaultRelayForwardingLimits = &ttnpb.ServingRelayForwardingLimits{
JoinRequests: &ttnpb.RelayForwardLimits{
BucketSize: ttnpb.RelayLimitBucketSize_RELAY_LIMIT_BUCKET_SIZE_2,
ReloadRate: 4,
Expand Down Expand Up @@ -142,7 +142,7 @@ func HandleRelayConfigureFwdLimitAns(
// either of these conditions is not true, the current serving parameters will be nil.
return nil
}
currentServing.Limits = &ttnpb.ServingRelayParameters_ForwardingLimits{
currentServing.Limits = &ttnpb.ServingRelayForwardingLimits{
ResetBehavior: req.ResetLimitCounter,
JoinRequests: req.JoinRequestLimits,
Notifications: req.NotifyLimits,
Expand Down
Loading
Loading