From 912fa0e0647871e8b74d7188d5dfc0ce6ec7c8bd Mon Sep 17 00:00:00 2001 From: norohind <60548839+norohind@users.noreply.github.com> Date: Sun, 7 Nov 2021 16:39:51 +0300 Subject: [PATCH 1/7] WIP: FSSSignalDiscovered event support --- schemas/fsssignaldiscovered-README.md | 1 + schemas/fsssignaldiscovered-v1.0.json | 81 +++++++++++++++++++++++++++ src/eddn/conf/Settings.py | 3 + 3 files changed, 85 insertions(+) create mode 100644 schemas/fsssignaldiscovered-README.md create mode 100644 schemas/fsssignaldiscovered-v1.0.json diff --git a/schemas/fsssignaldiscovered-README.md b/schemas/fsssignaldiscovered-README.md new file mode 100644 index 0000000..30404ce --- /dev/null +++ b/schemas/fsssignaldiscovered-README.md @@ -0,0 +1 @@ +TODO \ No newline at end of file diff --git a/schemas/fsssignaldiscovered-v1.0.json b/schemas/fsssignaldiscovered-v1.0.json new file mode 100644 index 0000000..51bd1f0 --- /dev/null +++ b/schemas/fsssignaldiscovered-v1.0.json @@ -0,0 +1,81 @@ +{ + "$schema" : "http://json-schema.org/draft-04/schema#", + "id" : "https://eddn.edcd.io/schemas/fsssignaldiscovered/1#", + "description" : "EDDN schema for FSSSignalDiscovered Journal events. Full documentation at https://github.com/EDCD/EDDN/tree/master/schemas/fsssignaldiscovered-README.md", + "type" : "object", + "additionalProperties" : false, + "required": [ "$schemaRef", "header", "message" ], + "properties": { + "$schemaRef": { + "type" : "string" + }, + "header": { + "type" : "object", + "additionalProperties" : true, + "required" : [ "uploaderID", "softwareName", "softwareVersion" ], + "properties" : { + "uploaderID": { + "type" : "string" + }, + "softwareName": { + "type" : "string" + }, + "softwareVersion": { + "type" : "string" + }, + "gatewayTimestamp": { + "type" : "string", + "format" : "date-time", + "description" : "Timestamp upon receipt at the gateway. If present, this property will be overwritten by the gateway; submitters are not intended to populate this property." + } + } + }, + "message": { + "type" : "object", + "description" : "Contains all properties from the listed events in the client's journal minus Localised strings and the properties marked below as 'disallowed'", + "additionalProperties" : false, + "required" : [ "event", "signals"], + "properties" : { + "event": { + "enum" : [ "FSSSignalDiscovered" ] + }, + "horizons": { + "type" : "boolean", + "description" : "Whether the sending Cmdr has a Horizons pass." + }, + "odyssey": { + "type" : "boolean", + "description" : "Whether the sending Cmdr has an Odyssey expansion." + }, + "signals": { + "type": "array", + "description": "Array of FSSSignalDiscovered events", + "minItems": 1, + "items": { + "type": "object", + "required": ["SystemAddress", "timestamp", "SignalName"], + "description": "Single FSSSignalDiscovered event", + "properties": { + "SystemAddress": { "type": "integer" }, + "timestamp": { + "type" : "string", + "format" : "date-time" + }, + "SignalName": { "type": "string" }, + "IsStation": { "type": "boolean" }, + "TimeRemaining": {"$ref" : "#/definitions/disallowed"}, + + "patternProperties": { + "_Localised$" : { "$ref" : "#/definitions/disallowed" } + } + } + } + } + + } + } + }, + "definitions": { + "disallowed" : { "not" : { "type": [ "array", "boolean", "integer", "number", "null", "object", "string" ] } } + } +} diff --git a/src/eddn/conf/Settings.py b/src/eddn/conf/Settings.py index c09e2ad..0b3253a 100644 --- a/src/eddn/conf/Settings.py +++ b/src/eddn/conf/Settings.py @@ -81,6 +81,9 @@ class _Settings(object): "https://eddn.edcd.io/schemas/fssbodysignals/1" : "schemas/fssbodysignals-v1.0.json", "https://eddn.edcd.io/schemas/fssbodysignals/1/test" : "schemas/fssbodysignals-v1.0.json", + + "https://eddn.edcd.io/schemasfsssignaldiscovered/1" : "schemas/fsssignaldiscovered-v1.0.json", + "https://eddn.edcd.io/schemasfsssignaldiscovered/1/test" : "schemas/fsssignaldiscovered-v1.0.json", } GATEWAY_OUTDATED_SCHEMAS = [ From 036e918fe93f5bb008323643ac23efea546c94c5 Mon Sep 17 00:00:00 2001 From: norohind <60548839+norohind@users.noreply.github.com> Date: Sun, 7 Nov 2021 17:41:42 +0300 Subject: [PATCH 2/7] FSSSignalDiscovered: optional systemName and StarPos --- schemas/fsssignaldiscovered-v1.0.json | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/schemas/fsssignaldiscovered-v1.0.json b/schemas/fsssignaldiscovered-v1.0.json index 51bd1f0..834cbe1 100644 --- a/schemas/fsssignaldiscovered-v1.0.json +++ b/schemas/fsssignaldiscovered-v1.0.json @@ -70,7 +70,20 @@ } } } - } + }, + "systemName": { + "type" : "string", + "minLength" : 1, + "description": "Should be added by the sender" + }, + "StarPos": { + "type" : "array", + "items" : { "type": "number" }, + "minItems" : 3, + "maxItems" : 3, + "description" : "Should be added by the sender" + } + } } From 5386ed2c64dc7223e6a494f235d77801fc313ab9 Mon Sep 17 00:00:00 2001 From: norohind <60548839+norohind@users.noreply.github.com> Date: Sun, 7 Nov 2021 18:34:07 +0300 Subject: [PATCH 3/7] FSSSignalDiscovered: add properties --- schemas/fsssignaldiscovered-v1.0.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/schemas/fsssignaldiscovered-v1.0.json b/schemas/fsssignaldiscovered-v1.0.json index 834cbe1..bb03da5 100644 --- a/schemas/fsssignaldiscovered-v1.0.json +++ b/schemas/fsssignaldiscovered-v1.0.json @@ -63,7 +63,11 @@ }, "SignalName": { "type": "string" }, "IsStation": { "type": "boolean" }, + "USSType": { "type": "string" }, "TimeRemaining": {"$ref" : "#/definitions/disallowed"}, + "SpawningState": {"type": "string"}, + "SpawningFaction" : {"type": "string"}, + "ThreatLevel": {"type": "integer" }, "patternProperties": { "_Localised$" : { "$ref" : "#/definitions/disallowed" } From 6dbc9e392a96db0d432291e54ceb5702118fd074 Mon Sep 17 00:00:00 2001 From: norohind <60548839+norohind@users.noreply.github.com> Date: Sun, 7 Nov 2021 19:22:05 +0300 Subject: [PATCH 4/7] FSSSignalDiscovered: don't pass `$USS_Type_MissionTarget;` USS_Type --- schemas/fsssignaldiscovered-v1.0.json | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/schemas/fsssignaldiscovered-v1.0.json b/schemas/fsssignaldiscovered-v1.0.json index bb03da5..d5e4fcc 100644 --- a/schemas/fsssignaldiscovered-v1.0.json +++ b/schemas/fsssignaldiscovered-v1.0.json @@ -63,7 +63,12 @@ }, "SignalName": { "type": "string" }, "IsStation": { "type": "boolean" }, - "USSType": { "type": "string" }, + "USSType": { + "type": "string", + "not": { + "pattern": "^\\$USS_Type_MissionTarget;$" + } + }, "TimeRemaining": {"$ref" : "#/definitions/disallowed"}, "SpawningState": {"type": "string"}, "SpawningFaction" : {"type": "string"}, From 03caeaa20c14ec93b89e718fa21e708159919517 Mon Sep 17 00:00:00 2001 From: norohind <60548839+norohind@users.noreply.github.com> Date: Sun, 7 Nov 2021 21:22:01 +0300 Subject: [PATCH 5/7] FSSSignalDiscovered: initial documentation --- schemas/fsssignaldiscovered-README.md | 53 ++++++++++++++++++++++++++- schemas/fsssignaldiscovered-v1.0.json | 6 +-- 2 files changed, 54 insertions(+), 5 deletions(-) diff --git a/schemas/fsssignaldiscovered-README.md b/schemas/fsssignaldiscovered-README.md index 30404ce..370006c 100644 --- a/schemas/fsssignaldiscovered-README.md +++ b/schemas/fsssignaldiscovered-README.md @@ -1 +1,52 @@ -TODO \ No newline at end of file +# EDDN FSSSignalDiscovered Schema + +## Introduction +Here we document how to take data from an ED `FSSSignalDiscovered` Journal +Event and properly structure it for sending to EDDN. + +Please consult [EDDN Schemas README](./README-EDDN-schemas.md) for general +documentation for a schema such as this. + +## Senders +The primary data source for this schema is the ED Journal event +`FSSSignalDiscovered`. + +### Batching +You MUST put several `FSSSignalDiscovered` events to an array `signals` which is key of `message`. Minimum size of +`signals` is 1 item. + +Do not make a request for every single event. + +Possible algorithm of batching: +1. If the event is FSSSignalDiscovered, store it to the temporal list and proceed to next event. +2. If the next event is also FSSSignalDiscovered, repeat 1. +3. If the next event is any other or there is no other event for more than 10 seconds, send the + temporal list in a single message to EDDN. + +### Elisions +You MUST remove the following key/value pairs from the data: + + - `TimeRemaining` key/value pair. + +You MUST refuse to send the whole `FSSSignalDiscovered` event if `USSType` key has `$USS_Type_MissionTarget;` value. + +### Augmentations +#### horizons flag +You SHOULD add this key/value pair, using the value from the `LoadGame` event. + +#### odyssey flag +You SHOULD add this key/value pair, using the value from the `LoadGame` event. + +#### systemName +You SHOULD add a `systemName` string containing the system name from the last `FSDJump`, `CarrierJump`, or `Location` +event There exists problem when you gets `FSSSignalDiscovered` before +`FSDJump`, `CarrierJump`, or `Location` event, so you MUST cross-check it with `SystemAddress` or don't include at all. + +#### StarPos +You SHOULD add a `StarPos` array containing the system co-ordinates from the +last `FSDJump`, `CarrierJump`, or `Location` event. There exists problem when you gets `FSSSignalDiscovered` before +`FSDJump`, `CarrierJump`, or `Location` event, so you MUST cross-check it with `SystemAddress` or don't include at all. + +## Receivers +Receivers should remember: `horizons`, `odyssey`, `systemName`, `StarPos` are optional key/value pairs, it means you +should not rely on it will appear in every EDDN event. diff --git a/schemas/fsssignaldiscovered-v1.0.json b/schemas/fsssignaldiscovered-v1.0.json index d5e4fcc..8d23066 100644 --- a/schemas/fsssignaldiscovered-v1.0.json +++ b/schemas/fsssignaldiscovered-v1.0.json @@ -76,10 +76,10 @@ "patternProperties": { "_Localised$" : { "$ref" : "#/definitions/disallowed" } + } } } - } - }, + }, "systemName": { "type" : "string", "minLength" : 1, @@ -92,8 +92,6 @@ "maxItems" : 3, "description" : "Should be added by the sender" } - - } } }, From fb9904306b7b4177a2ef1fc0b41011d244d7a27a Mon Sep 17 00:00:00 2001 From: norohind <60548839+norohind@users.noreply.github.com> Date: Sun, 7 Nov 2021 23:59:20 +0300 Subject: [PATCH 6/7] FSSSignalDiscovered doc: add examples --- schemas/fsssignaldiscovered-README.md | 70 +++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/schemas/fsssignaldiscovered-README.md b/schemas/fsssignaldiscovered-README.md index 370006c..5ada0e9 100644 --- a/schemas/fsssignaldiscovered-README.md +++ b/schemas/fsssignaldiscovered-README.md @@ -50,3 +50,73 @@ last `FSDJump`, `CarrierJump`, or `Location` event. There exists problem when yo ## Receivers Receivers should remember: `horizons`, `odyssey`, `systemName`, `StarPos` are optional key/value pairs, it means you should not rely on it will appear in every EDDN event. + +## Examples +This is a few example of messages that passes current `FSSSignalDiscovered` schema. +1. A message without `horizons`, `odyssey`, `systemName`, `StarPos` fields. +```json +{ + "$schemaRef":"https://eddn.edcd.io/schemas/fsssignaldiscovered/1", + "header":{ + "gatewayTimestamp":"2021-11-06T22:48:43.483147Z", + "softwareName":"an software", + "softwareVersion":"a version", + "uploaderID":"an uploader" + }, + "message":{ + "event":"FSSSignalDiscovered", + "signals":[ + { + "timestamp":"2021-07-30T19:03:08Z", + "event":"FSSSignalDiscovered", + "SystemAddress":1774711381, + "SignalName":"EXPLORER-CLASS X2X-74M", + "IsStation":true + } + ] + } +} +``` + +2. A message with `horizons`, `odyssey`, `systemName`, `StarPos` fields. +```json +{ + "$schemaRef":"https://eddn.edcd.io/schemas/fsssignaldiscovered/1", + "header":{ + "gatewayTimestamp":"2021-11-06T22:48:43.483147Z", + "softwareName":"an software", + "softwareVersion":"a version", + "uploaderID":"an uploader" + }, + "message":{ + "event":"FSSSignalDiscovered", + "signals":[ + { + "timestamp":"2021-07-30T19:03:08Z", + "event":"FSSSignalDiscovered", + "SystemAddress":1774711381, + "SignalName":"EXPLORER-CLASS X2X-74M", + "IsStation":true + }, + { + "timestamp":"2020-12-31T14:14:01Z", + "event":"FSSSignalDiscovered", + "SystemAddress":216054883492, + "SignalName":"$USS_NonHumanSignalSource;", + "USSType":"$USS_Type_NonHuman;", + "SpawningState":"$FactionState_None;", + "SpawningFaction":"$faction_none;", + "ThreatLevel":5 + } + ], + "StarPos": [ + 8.1875, + 124.21875, + -38.5 + ], + "StarSystem": "HIP 56186", + "horizons": true, + "odyssey": true + } +} +``` From 732de9bdd635f22a56e76220f0f5546c0cb0abf8 Mon Sep 17 00:00:00 2001 From: norohind <60548839+norohind@users.noreply.github.com> Date: Mon, 8 Nov 2021 00:00:39 +0300 Subject: [PATCH 7/7] FSSSignalDiscovered doc --- schemas/fsssignaldiscovered-README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/schemas/fsssignaldiscovered-README.md b/schemas/fsssignaldiscovered-README.md index 5ada0e9..f07d8ae 100644 --- a/schemas/fsssignaldiscovered-README.md +++ b/schemas/fsssignaldiscovered-README.md @@ -78,7 +78,7 @@ This is a few example of messages that passes current `FSSSignalDiscovered` sche } ``` -2. A message with `horizons`, `odyssey`, `systemName`, `StarPos` fields. +2. A message with `horizons`, `odyssey`, `systemName`, `StarPos` fields which says it sent from Odyssey. ```json { "$schemaRef":"https://eddn.edcd.io/schemas/fsssignaldiscovered/1",