chore: add rfc1 back

Author: pepperoni505

docs/RFC001.md

@@ -0,0 +1,208 @@
+# Developer-Oriented In-Sim Navigation Data API Specification
+
+To be Reviewed By: Markus Hamburger, Malte Hallström, Jack Lavigne
+
+Authors: Alex Cutforth
+
+Status: Outdated
+
+Date: Feb 1, 2024
+
+## Problem
+
+Accessing Navigraph's navigation data in Microsoft Flight Simulator has always been challenging due to the limitations of the JavaScript and Webassembly APIs. However, with the recent addition of the Communications API, allowing different WASM modules and Coherent pages to interact with each other, this has become possible.
+
+Navigraph has decided to use an architecture consisting of a wasm module whose job it is to download navigation data databases from the internet, and to query them. This means an API must be designed and implemented to best cater to the needs of aircraft developers.
+
+This RFC will outline the following:
+
+- Naming, typing, and other standards to use throughout the API
+- Example data structures for the returned data which are comprehensive and ergonomic to use
+- Example functions the API will implement to provide the necessary data.
+
+## Anti-Goals
+
+This interface will not be designed for use in parallel with in sim data, it is meant to provide the best experience possible with Navigraph's navigation data capabilities. This interface will only be providing data from Navigraph's databases.
+
+This interface is also not designed for use outside of Microsoft Flight Simulator and is not designed (as of now) with anything other than the Flight Management System in mind.
+
+# Solution
+
+## Standards
+
+---
+
+- All functions and fields and variables involved in this interface should use `snake_case`, and all names of objects and types should use `PascalCase`. This is the code style which rust uses, and it should be used JS side as well for consistency and so objects dont need to be re assigned.
+- Data fields which act as an identifier should always use the shorthand term: `ident` and should not name the type they are part of.
+  - Example: Runways may contain the fields:
+    - `ident: "RW23L"`
+    - `airport_ident: "NZAA"`
+  - Example: Airports may contain the field:
+    - `ident: "NZAA"`
+- Using the term `icao` to refer to an identifier is an anti-pattern as it may be confused with the `icao_code` which contains a two-letter code such as `ES` which represents the area of the world where this piece of data lies.
+  - Example: Airports may contain the fields:
+    - `icao_code: "NZ"`
+    - `ident: "NZAA"`
+- Fields should represent the unit that the data will be using as a type alias, not by a suffix or prefix to the name of the field.
+  - Do: `runway_length: Feet`
+  - Don't: `runway_length_ft: number`
+- Radio navigation aid data type names should consist of the acronym of the type, followed by the suffix `Navaid`
+  - Examples: `VhfNavaid`, `IlsNavaid`, `NdbNavaid`,
+- Acronyms should **_not_** be all capitalised
+  - Do: `Vhf`
+  - Dont: `NDB`
+- Latitudes should be encoded to as `lat` and Longitudes should be encoded to as `long`, and should wherever they are used in conjunction with each other, be part of a `Coordinates` data structure
+
+---
+
+- Items which are linked to other data should **_not_** have the linked data queried automatically and added to the returned data.
+  - This is because increasing the size of data this much will result in slower queries due to the performance issues with Coherent's JSON parser.
+  - While it is useful to have linked data such as Navaid information on airway or procedures, this would not be viable when using the API in a language other than JS or Rust
+- For items such as Procedures and Airways, which are represented in the database as a large number of rows with the same `ident` and possibly `icao_code`. They should be grouped into an object, containing list(s) which stores the individual elements. Fields which are known to be the same throughout the grouping should be on the group object, not the individual elements.
+  - If the individual elements are split into sections such as transitions in a procedure, these should be encoded as subgroups.
+
+---
+
+- Data should be provided in the same units that the Database provides for consistency with aviation standards
+- Enums should be used where possible and should have values which match the database encoding.
+  - Except for when an enum is to be used as a filter, where its values should support bitwise flags.
+- The data provided by this API should be able to be encoded purely in JSON, meaning:
+
+  - No functions
+  - No classes
+  - This is to support JSON serialization as a form of copying or sending between instruments
+
+- Data fields should never be empty strings, they should be undefined
+- Data fields which are linked to each other will either both be undefined or both be defined
+- Data being encoded as possibly undefined should be based on database sweeps to find whether there are any null fields, not the database schema.
+
+- Datastructures which are expected to have certain fields be defined based on the value of another field should have the type-system enforce this where possible, for example:
+
+  - Procedure legs will have their fields filtered based upon the `path_termination` field. Specs for this can be found [here](https://developers.navigraph.com/docs/navigation-data/dfd-data-format#procedure-leg-data-fields-minimum-requirements) or in `ARINC SPECIFICATION 424 Attachment 5 Data fields table 3`
+  - Altitude constraints
+
+- Values which are not defined should be undefined as opposed to null. This means in the rust implementation, all structs used for serialization which have Option fields should have `#[serde_with::skip_serializing_none]` as an attribute about the struct
+
+---
+
+- Functions which fetch items by the identifier should be named as `get_{type}s`
+- Functions which fetch a list of items by a grouping should be named `get_{type}_at_{group}` and should take in the identifier of the item used as the grouping
+- Functions which fetch a list of items by location and range should use the naming: `get_{type}s_in_range`, and should take in:
+  - The center coordinates of the query
+  - The range in nautical miles to search around the center
+  - Any filters necessary for the type being fetched
+
+---
+
+- In the rust implementation, Mapping one row to one output struct should use a From<> implementation, but any other mapping should be done with a descriptively named function
+
+---
+
+## Example Datastructures
+
+These datastructures are for use in JS/TS, however, they should be encoded as close to this as they can be on the WASM side, so minimal computation needs to happen in Coherent.
+
+```ts
+export interface Coordinates {
+  lat: Degrees
+  long: Degrees
+}
+```
+
+For data which links to a Fix such as Departures, Arrivals, Airways etc should use the Fix interface as the type for those fields. The data in Fix should be obtainable purely from id fields and location field.
+
+The Fix data will be enough information for computing and rendering procedures and airways on most aircraft. After reading the fixType field, full data for the Fix can be fetched using the respective queries.
+
+```ts
+export enum FixType {
+  Airport,
+  NdbNavaid,
+  RunwayThreshold,
+  GlsNavaid,
+  IlsNavaid,
+  VhfNavaid,
+  Waypoint,
+}
+
+interface Fix {
+  fix_type: FixType
+  ident: string
+  icao_code: string
+  location: Coordinates
+  airport_ident?: string
+}
+```
+
+```ts
+interface Transition {
+  ident: string
+  legs: ProcedureLeg[]
+}
+
+interface Departure {
+  ident: string
+  runway_transitions: Transition[]
+  common_legs: ProcedureLeg[]
+  enroute_transitions: Transition[]
+  engine_out_legs: ProcedureLeg[]
+}
+```
+
+```ts
+export interface Airport {
+  area_code: string
+  ident_3_letter?: string
+  name: string
+  ifr_capability: IfrCapability
+  elevation: Feet
+  transition_altitude?: Feet
+  transition_level?: Feet
+  speed_limit?: Knots
+  speed_limit_altitude?: Feet
+  iata_ident?: string
+}
+```
+
+```ts
+export interface Airway {
+  ident: string
+  fixes: Fix[]
+  route_type: RouteType
+  level: AirwayLevel
+  direction?: AirwayDirection
+}
+```
+
+## Full description of functions to be implemented
+
+```ts
+get_database_info(ident: string): Promise<Airport>
+
+get_airport(ident: string): Promise<Airport>
+get_waypoints(ident: string): Promise<Waypoint[]>
+get_vhf_navaids(ident: string): Promise<VhfNavaid[]>
+get_ndb_navaids(ident: string): Promise<NdbNavaid[]>
+get_airways(ident: string): Promise<Airway[]>
+
+get_airways_at_fix(fix_ident: string, fix_icao_code: string): Promise<Airway[]>
+get_holds_at_fix(fix_ident: string, fix_icao_code: string): Promise<Hold[]>
+
+get_waypoints_in_range(center: Coordinates, range: NauticalMiles): Promise<Waypoint[]>
+get_vhf_navaids_in_range(center: Coordinates, range: NauticalMiles): Promise<VhfNavaid[]>
+get_ndb_navaids_in_range(center: Coordinates, range: NauticalMiles): Promise<NdbNavaid[]>
+get_airways_in_range(center: Coordinates, range: NauticalMiles): Promise<Airway[]>
+get_controlled_airspaces_in_range(center: Coordinates, range: NauticalMiles): Promise<ControlledAirspace[]>
+get_restrictive_airspaces_in_range(center: Coordinates, range: NauticalMiles): Promise<RestrictiveAirspace[]>
+get_communications_in_range(center: Coordinates, range: NauticalMiles): Promise<Communication[]>
+
+get_runways_at_airport(airport_ident: string): Promise<Runway[]>
+get_departures_at_airport(airport_ident: string): Promise<Departure[]>
+get_arrivals_at_airport(airport_ident: string): Promise<Arrival[]>
+get_approaches_at_airport(airport_ident: string): Promise<Approach[]>
+get_ndb_navaids_at_airport(airport_ident: string): Promise<NdbNavaid[]>
+get_ils_navaids_at_airport(airport_ident: string): Promise<IlsNavaid[]>
+get_gls_navaids_at_airport(airport_ident: string): Promise<GlsNavaid[]>
+get_path_points_at_airport(airport_ident: string): Promise<GlsNavaid[]>
+get_communications_at_airport(airport_ident: string): Promise<Communication[]>
+get_gates_at_airport(airport_ident: string): Promise<Gate[]>
+```