From daa82adb11f912fee06238bbd714b0dda1ece2d0 Mon Sep 17 00:00:00 2001 From: Dimitri Benin Date: Fri, 1 Feb 2019 16:47:51 +0100 Subject: [PATCH] [onionoo] Add types --- types/onionoo/index.d.ts | 820 +++++++++++++++++++++++++++++++++ types/onionoo/onionoo-tests.ts | 38 ++ types/onionoo/tsconfig.json | 28 ++ types/onionoo/tslint.json | 1 + 4 files changed, 887 insertions(+) create mode 100644 types/onionoo/index.d.ts create mode 100644 types/onionoo/onionoo-tests.ts create mode 100644 types/onionoo/tsconfig.json create mode 100644 types/onionoo/tslint.json diff --git a/types/onionoo/index.d.ts b/types/onionoo/index.d.ts new file mode 100644 index 0000000000..23d19b7c92 --- /dev/null +++ b/types/onionoo/index.d.ts @@ -0,0 +1,820 @@ +// Type definitions for onionoo 2.0 +// Project: https://github.com/lukechilds/onionoo-node-client +// Definitions by: BendingBender +// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped +// TypeScript Version: 3.0 + +import { Cache, GotPromise } from 'got'; + +export = Oninoo; + +declare const Oninoo: Onionoo; + +interface Onionoo { + new (options?: Onionoo.Options): Onionoo.Instance & Onionoo.Endpoints; + new (options: Onionoo.OptionsWithEndpoints): Onionoo.Instance & Partial; +} + +declare namespace Onionoo { + interface Instance { + get(endpoint: 'summary', query?: QueryParameters): GotPromise; + get(endpoint: 'details', query?: QueryParameters): GotPromise
; + get(endpoint: 'bandwidth', query?: QueryParameters): GotPromise; + get(endpoint: 'weights', query?: QueryParameters): GotPromise; + get(endpoint: 'clients', query?: QueryParameters): GotPromise; + get(endpoint: 'uptime', query?: QueryParameters): GotPromise; + } + + interface Endpoints { + summary(query?: QueryParameters): GotPromise; + details(query?: QueryParameters): GotPromise
; + bandwidth(query?: QueryParameters): GotPromise; + weights(query?: QueryParameters): GotPromise; + clients(query?: QueryParameters): GotPromise; + uptime(query?: QueryParameters): GotPromise; + } + + interface Options { + /** + * String to use as the base url for all API requests. + * @default 'https://onionoo.torproject.org' + */ + baseUrl?: string; + /** + * Storage adapter instance for storing cached data. + * @default false + */ + cache?: Cache | false; + } + + interface OptionsWithEndpoints extends Options { + /** + * Array of endpoints to be returned as methods on the `Onionoo` instance. + * @default ['summary', 'details', 'bandwidth', 'weights', 'clients', 'uptime'] + */ + endpoints: Array<'summary' | 'details' | 'bandwidth' | 'weights' | 'clients' | 'uptime'>; + } + + interface QueryParameters { + /** + * Return only `relay` or only `bridge` documents. + */ + type?: 'relay' | 'bridge'; + /** + * Return only running (`true`) or only non-running relays and/or bridges (`false`). + */ + running?: boolean; + /** + * Return only (1) relays with the parameter value matching (part of a) nickname, (possibly $-prefixed) + * beginning of a hex-encoded fingerprint, any 4 hex character block of a space-separated fingerprint, + * beginning of a base64-encoded fingerprint without trailing equal signs, or beginning of an IP address + * (possibly enclosed in square brackets in case of IPv6), (2) bridges with (part of a) nickname + * or (possibly $-prefixed) beginning of a hashed hex-encoded fingerprint, and (3) relays and/or bridges + * matching a given qualified search term. Searches by relay IP address include all known addresses used + * for onion routing and for exiting to the Internet. Searches for beginnings of IP addresses are performed + * on textual representations of canonical IP address forms, so that searches using CIDR notation or + * non-canonical forms will return empty results. Searches are case-insensitive, except for base64-encoded + * fingerprints. If multiple search terms are given, separated by spaces, the intersection of all relays + * and bridges matching all search terms will be returned. Complete hex-encoded fingerprints should always + * be hashed using SHA-1, regardless of searching for a relay or a bridge, in order to not accidentally + * leak non-hashed bridge fingerprints in the URL. Qualified search terms have the form "key:value" + * (without double quotes) with "key" being one of the parameters listed here except for "search", + * "fingerprint", "order", "limit", "offset", and "fields", and "value" being the string that will + * internally be passed to that parameter. If a qualified search term for a given "key" is specified + * more than once, only the first "value" is considered. + */ + search?: string; + /** + * Return only the relay with the parameter value matching the fingerprint or the bridge with the parameter + * value matching the hashed fingerprint. Fingerprints should always be hashed using SHA-1, regardless of + * looking up a relay or a bridge, in order to not accidentally leak non-hashed bridge fingerprints in the URL. + * Lookups only work for full fingerprints or hashed fingerprints consisting of 40 hex characters. + * Lookups are case-insensitive. + */ + lookup?: string; + /** + * Return only relays which are located in the given country as identified by a two-letter country code. + * Filtering by country code is case-insensitive. The special country code xz can be used for relays that + * were not found in the GeoIP database. + */ + country?: string; + /** + * Return only relays which are located in either one of the given autonomous systems (AS) as identified + * by AS number (with or without preceding "AS" part). Multiple AS numbers can be provided separated by commas. + * Filtering by AS number is case-insensitive. The special AS number 0 can be used for relays that were + * not found in the GeoIP database. + */ + as?: string; + /** + * Return only relays with the parameter value matching (part of) the autonomous system (AS) name they are + * located in. If the parameter value contains spaces, only relays are returned which contain all + * space-separated parts in their AS name. Only printable ASCII characters are permitted in the parameter + * value, some of which need to be percent-encoded (# as %23, % as %25, & as %26, + as %2B, and / as %2F). + * Comparisons are case-insensitive. + */ + as_name?: string; + /** + * Return only relays which have the given relay flag assigned by the directory authorities. + * Filtering by flag is case-insensitive. + */ + flag?: string; + /** + * Return only relays or bridges which have first been seen during the given range of days ago. A parameter + * value "x-y" with x <= y returns relays or bridges that have first been seen at least x and at most y days ago. + * Accepted short forms are "x", "x-", and "-y" which are interpreted as "x-x", "x-infinity", and "0-y". + */ + first_seen_days?: string; + /** + * Return only relays or bridges which have last been seen during the given range of days ago. A parameter + * value "x-y" with x <= y returns relays or bridges that have last been seen at least x and at most y days ago. + * Accepted short forms are "x", "x-", and "-y" which are interpreted as "x-x", "x-infinity", and "0-y". + * Note that relays and bridges that haven't been running in the past week are not included in results, + * so that setting x to 8 or higher will lead to an empty result set. + */ + last_seen_days?: string; + /** + * Return only relays with the parameter value matching (part of) the contact line. If the parameter value + * contains spaces, only relays are returned which contain all space-separated parts in their contact line. + * Only printable ASCII characters are permitted in the parameter value, some of which need to be + * percent-encoded (# as %23, % as %25, & as %26, + as %2B, and / as %2F). Comparisons are case-insensitive. + */ + contact?: string; + /** + * Return only the relay whose fingerprint matches the parameter value and all relays that this relay has + * listed in its family by fingerprint and that in turn have listed this relay in their family by fingerprint. + * If relays have listed other relays in their family by nickname, those family relationships will not be + * considered, regardless of whether they have the Named flag or not. The provided relay fingerprint must + * consist of 40 hex characters where case does not matter, and it must not be hashed using SHA-1. + * Bridges are not contained in the result, regardless of whether they define a family. + */ + family?: string; + /** + * Return only relays or bridges running either Tor version from a list or range given in the parameter value. + * Tor versions must be provided without the leading "Tor" part. Multiple versions can either be provided as a + * comma-separated list (","), as a range separated by two dots (".."), or as a list of ranges. + * Provided versions are parsed and matched by parsed dotted numbers, rather than by string prefix. + */ + version?: string; + /** + * Return only relays or bridges running on an operating system that starts with the parameter value. + * Searches are case-insensitive. + */ + os?: string; + /** + * Return only relays with a domain name ending in the given (partial) host name. Searches for subdomains + * of a specific domain should ideally be prefixed with a period, for example: ".csail.mit.edu". Non-ASCII + * host name characters must be encoded as punycode. Filtering by host name is case-insensitive. + */ + host_name?: string; + /** + * Return only relays and bridges running a Tor software version that is recommended (`true`) or not + * recommended by the directory authorities (`false`). Uses the version in the consensus or bridge network status. + * Relays and bridges are not contained in either result, if the version they are running is not known. + */ + recommended_version?: boolean; + /** + * Response documents can be reduced in size by requesting only a subset of contained fields. + * Comma-separated list of fields that will be included in the result. So far, only top-level fields + * in relay or bridge objects of details documents can be specified, e.g., `nickname,hashed_fingerprint`. + * If the fields parameter is provided, all other fields which are not contained in the provided list + * will be removed from the result. + */ + fields?: string[]; + /** + * Re-order results by a comma-separated list of fields in ascending or descending order. Results are first + * ordered by the first list element, then by the second, and so on. Possible fields for ordering are: + * `consensus_weight` and `first_seen`. Ascending order is the default; descending order is selected by + * prepending fields with a minus sign (-). Field names can be listed at most once in either ascending or + * descending order. Relays or bridges which don't have any value for a field to be ordered by are always + * appended to the end, regardless or sorting order. The ordering is defined independent of the requested + * document type and does not require the ordering field to be contained in the document. If no `order` + * parameter is given, ordering of results is undefined. + */ + order?: string; + + /** + * Skip the given number of relays and/or bridges. Relays are skipped first, then bridges. + * Non-positive `offset` values are treated as zero and don't change the result. + */ + offset?: number; + /** + * Limit result to the given number of relays and/or bridges. Relays are kept first, then bridges. + * Non-positive `limit` values are treated as zero and lead to an empty result. When used together with `offset`, + * the offsetting step precedes the limiting step. + */ + limit?: number; + } + + type Summary = Response; + type Details = Response; + type Bandwidth = Response; + type Weights = Response; + type Clients = Response; + type Uptime = Response; + + interface Response { + /** + * Onionoo protocol version string. + */ + version: string; + /** + * UTC date (YYYY-MM-DD) when the next major protocol version is scheduled to be deployed. Omitted if no major + * protocol changes are planned. + */ + next_major_version_scheduled?: string; + /** + * Git revision of the Onionoo instance's software used to write this response, which will be omitted if unknown. + */ + build_revision?: string; + /** + * UTC timestamp (YYYY-MM-DD hh:mm:ss) when the last known relay network status consensus started being valid. + * Indicates how recent the relay objects in this document are. + */ + relays_published: string; + /** + * Number of skipped relays as requested by a positive "offset" parameter value. Omitted if zero. + */ + relays_skipped?: number; + relays: TRelay[]; + /** + * Number of truncated relays as requested by a positive "limit" parameter value. Omitted if zero. + */ + relays_truncated?: number; + /** + * UTC timestamp (YYYY-MM-DD hh:mm:ss) when the last known bridge network status was published. + * Indicates how recent the bridge objects in this document are. + */ + bridges_published: string; + /** + * Number of skipped bridges as requested by a positive `offset` parameter value. Omitted if zero. + */ + bridges_skipped?: number; + bridges: TBridge[]; + /** + * Number of truncated bridges as requested by a positive `limit` parameter value. Omitted if zero. + */ + bridges_truncated?: number; + } + + interface RelaySummary { + /** + * Relay nickname consisting of 1–19 alphanumerical characters. + */ + n: string; + /** + * Relay fingerprint consisting of 40 upper-case hexadecimal characters. + */ + f: string; + /** + * Array of IPv4 or IPv6 addresses where the relay accepts onion-routing connections or which the relay + * used to exit to the Internet in the past 24 hours. The first address is the primary onion-routing address + * that the relay used to register in the network, subsequent addresses are in arbitrary order. IPv6 hex + * characters are all lower-case. + */ + a: string[]; + /** + * Boolean field saying whether this relay was listed as running in the last relay network status consensus. + */ + r: boolean; + } + + interface Relay { + /** + * Relay nickname consisting of 1–19 alphanumerical characters. + */ + nickname: string; + /** + * Relay fingerprint consisting of 40 upper-case hexadecimal characters. + */ + fingerprint: string; + /** + * Array of IPv4 or IPv6 addresses and TCP ports or port lists where the relay accepts onion-routing connections. + * The first address is the primary onion-routing address that the relay used to register in the network, + * subsequent addresses are in arbitrary order. IPv6 hex characters are all lower-case. + */ + or_addresses: string[]; + /** + * Array of IPv4 addresses that the relay used to exit to the Internet in the past 24 hours. Omitted if + * array is empty. Includes all exit addresses, regardless of whether they are used as onion-routing addresses + * or not. + */ + exit_addresses?: string[]; + /** + * IPv4 address and TCP port where the relay accepts directory connections. + * Omitted if the relay does not accept directory connections. + */ + dir_address?: string; + /** + * UTC timestamp (YYYY-MM-DD hh:mm:ss) when this relay was last seen in a network status consensus. + */ + last_seen: string; + /** + * UTC timestamp (YYYY-MM-DD hh:mm:ss) when this relay last stopped announcing an IPv4 or IPv6 address or + * TCP port where it previously accepted onion-routing or directory connections. This timestamp can serve + * as indicator whether this relay would be a suitable fallback directory. + */ + last_changed_address_or_port: string; + /** + * UTC timestamp (YYYY-MM-DD hh:mm:ss) when this relay was first seen in a network status consensus. + */ + first_seen: string; + /** + * Boolean field saying whether this relay was listed as running in the last relay network status consensus. + */ + running: boolean; + /** + * Boolean field saying whether this relay indicated that it is hibernating in its last known server descriptor. + * This information may be helpful to decide whether a relay that is not running anymore has reached its + * accounting limit and has not dropped out of the network for another, unknown reason. Omitted if either + * the relay is not hibernating, or if no information is available about the hibernation status of the relay. + */ + hibernating?: boolean; + /** + * Array of relay flags that the directory authorities assigned to this relay. May be omitted if empty. + */ + flags?: string[]; + /** + * Two-letter lower-case country code as found in a GeoIP database by resolving the relay's first + * onion-routing IP address. Omitted if the relay IP address could not be found in the GeoIP database. + */ + country?: string; + /** + * Country name as found in a GeoIP database by resolving the relay's first onion-routing IP address. + * Omitted if the relay IP address could not be found in the GeoIP database, or if the GeoIP database + * did not contain a country name. + */ + country_name?: string; + /** + * Region name as found in a GeoIP database by resolving the relay's first onion-routing IP address. + * Omitted if the relay IP address could not be found in the GeoIP database, or if the GeoIP database + * did not contain a region name. + */ + region_name?: string; + /** + * City name as found in a GeoIP database by resolving the relay's first onion-routing IP address. + * Omitted if the relay IP address could not be found in the GeoIP database, or if the GeoIP database + * did not contain a city name. + */ + city_name?: string; + /** + * Latitude as found in a GeoIP database by resolving the relay's first onion-routing IP address. + * Omitted if the relay IP address could not be found in the GeoIP database. + */ + latitude?: number; + /** + * Longitude as found in a GeoIP database by resolving the relay's first onion-routing IP address. + * Omitted if the relay IP address could not be found in the GeoIP database. + */ + longitude?: number; + /** + * AS number as found in an AS database by resolving the relay's first onion-routing IP address. + * AS number strings start with "AS", followed directly by the AS number. Omitted if the relay IP + * address could not be found in the AS database. + */ + as?: string; + /** + * AS name as found in an AS database by resolving the relay's first onion-routing IP address. + * Omitted if the relay IP address could not be found in the AS database. + */ + as_name?: string; + /** + * Weight assigned to this relay by the directory authorities that clients use in their path selection algorithm. + * The unit is arbitrary; currently it's kilobytes per second, but that might change in the future. + */ + consensus_weight: number; + /** + * Host name as found in a reverse DNS lookup of the relay's primary IP address. This field is updated at most + * once in 12 hours, unless the relay IP address changes. Omitted if the relay IP address was not looked up, + * if no lookup request was successful yet, or if no A record was found matching the PTR record. + * @deprecated + */ + host_name?: string; + /** + * Host names as found in a reverse DNS lookup of the relay's primary IP address for which a matching A record + * was also found. This field is updated at most once in 12 hours, unless the relay IP address changes. + * Omitted if the relay IP address was not looked up, if no lookup request was successful yet, or if no + * A records were found matching the PTR records (i.e. it was not possible to verify the value of any + * of the PTR records). A DNSSEC validating resolver is used for these lookups. Failure to validate + * DNSSEC signatures will prevent those names from appearing in this field. + */ + verified_host_names?: string[]; + /** + * Host names as found in a reverse DNS lookup of the relay's primary IP address that for which a matching + * A record was not found. This field is updated at most once in 12 hours, unless the relay IP address changes. + * Omitted if the relay IP address was not looked up, if no lookup request was successful yet, or if A records + * were found matching all PTR records (i.e. it was possible to verify the value of each of the PTR records). + * A DNSSEC validating resolver is used for these lookups. Failure to validate DNSSEC signatures will prevent + * those names from appearing in this field. + */ + unverified_host_names?: string[]; + /** + * UTC timestamp (YYYY-MM-DD hh:mm:ss) when the relay was last (re-)started. + * Missing if router descriptor containing this information cannot be found. + */ + last_restarted?: string; + /** + * Average bandwidth in bytes per second that this relay is willing to sustain over long periods. + * Missing if router descriptor containing this information cannot be found. + */ + bandwidth_rate?: number; + /** + * Bandwidth in bytes per second that this relay is willing to sustain in very short intervals. + * Missing if router descriptor containing this information cannot be found. + */ + bandwidth_burst?: number; + /** + * Bandwidth estimate in bytes per second of the capacity this relay can handle. The relay remembers + * the maximum bandwidth sustained output over any ten second period in the past day, and another + * sustained input. The `observed_bandwidth` value is the lesser of these two numbers. Missing if + * router descriptor containing this information cannot be found. + */ + observed_bandwidth?: number; + /** + * Bandwidth in bytes per second that this relay is willing and capable to provide. This bandwidth + * value is the minimum of `bandwidth_rate`, `bandwidth_burst`, and `observed_bandwidth`. + * Missing if router descriptor containing this information cannot be found. + */ + advertised_bandwidth?: number; + /** + * Array of exit-policy lines. Missing if router descriptor containing this information cannot be found. + * May contradict the `exit_policy_summary` field in a rare edge case: this happens when the relay changes + * its exit policy after the directory authorities summarized the previous exit policy. + */ + exit_policy?: string[]; + /** + * Summary version of the relay's exit policy containing a dictionary with either an `accept` or a `reject` element. + * If there is an `accept` (`reject`) element, the relay accepts (rejects) all TCP ports or port ranges + * in the given list for most IP addresses and rejects (accepts) all other ports. May contradict the + * `exit_policy` field in a rare edge case: this happens when the relay changes its exit policy after + * the directory authorities summarized the previous exit policy. + */ + exit_policy_summary?: { + accept?: string[]; + reject?: string[]; + }; + /** + * Summary version of the relay's IPv6 exit policy containing a dictionary with either an `accept` or a `reject` + * element. If there is an `accept` (`reject`) element, the relay accepts (rejects) all TCP ports or port ranges + * in the given list for most IP addresses and rejects (accepts) all other ports. Missing if the relay rejects + * all connections to IPv6 addresses. May contradict the `exit_policy_summary` field in a rare edge case: + * this happens when the relay changes its exit policy after the directory authorities summarized the previous + * exit policy. + */ + exit_policy_v6_summary?: { + accept?: string[]; + reject?: string[]; + }; + /** + * Contact address of the relay operator. Omitted if empty or if descriptor containing this information + * cannot be found. + */ + contact?: string; + /** + * Platform string containing operating system and Tor version details. Omitted if empty or if descriptor + * containing this information cannot be found. + */ + platform?: string; + /** + * Tor software version without leading "Tor" as reported by the directory authorities in the "v" line of + * the consensus. Omitted if either the directory authorities or the relay did not report which version + * the relay runs or if the relay runs an alternative Tor implementation. + */ + version?: string; + /** + * Boolean field saying whether the Tor software version of this relay is recommended by the directory + * authorities or not. Uses the relay version in the consensus. Omitted if either the directory authorities + * did not recommend versions, or the relay did not report which version it runs. + */ + recommended_version?: boolean; + /** + * Status of the Tor software version of this relay based on the versions recommended by the directory authorities. + * Possible version statuses are: `recommended` if a version is listed as recommended; `experimental` if a version + * is newer than every recommended version; `obsolete` if a version is older than every recommended version; + * `new in series` if a version has other recommended versions with the same first three components, + * and the version is newer than all such recommended versions, but it is not newer than every recommended version; + * `unrecommended` if none of the above conditions hold. Omitted if either the directory authorities did not + * recommend versions, or the relay did not report which version it runs. + */ + version_status?: + | 'recommended' + | 'experimental' + | 'obsolete' + | 'new in series' + | 'unrecommended'; + /** + * Array of fingerprints of relays that are in an effective, mutual family relationship with this relay. + * These relays are part of this relay's family and they consider this relay to be part of their family. + * Always contains the relay's own fingerprint. Omitted if the descriptor containing this information + * cannot be found. + */ + effective_family?: string[]; + /** + * Array of fingerprints of relays that are not in an effective, mutual family relationship with this relay. + * These relays are part of this relay's family but they don't consider this relay to be part of their family. + * Omitted if empty or if descriptor containing this information cannot be found. + */ + alleged_family?: string[]; + /** + * Array of fingerprints of relays that are not in an effective, mutual family relationship with this relay + * but that can be reached by following effective, mutual family relationships starting at this relay. + * Omitted if empty or if descriptor containing this information cannot be found. + */ + indirect_family?: string[]; + /** + * Fraction of this relay's consensus weight compared to the sum of all consensus weights in the network. + * This fraction is a very rough approximation of the probability of this relay to be selected by clients. + * Omitted if the relay is not running. + */ + consensus_weight_fraction?: number; + /** + * Probability of this relay to be selected for the guard position. This probability is calculated based on + * consensus weights, relay flags, and bandwidth weights in the consensus. Path selection depends on more + * factors, so that this probability can only be an approximation. Omitted if the relay is not running, + * or the consensus does not contain bandwidth weights. + */ + guard_probability?: number; + /** + * Probability of this relay to be selected for the middle position. This probability is calculated based on + * consensus weights, relay flags, and bandwidth weights in the consensus. Path selection depends on more + * factors, so that this probability can only be an approximation. Omitted if the relay is not running, + * or the consensus does not contain bandwidth weights. + */ + middle_probability?: number; + /** + * Probability of this relay to be selected for the exit position. This probability is calculated based on + * consensus weights, relay flags, and bandwidth weights in the consensus. Path selection depends on more + * factors, so that this probability can only be an approximation. Omitted if the relay is not running, + * or the consensus does not contain bandwidth weights. + */ + exit_probability?: number; + /** + * Boolean field saying whether the consensus weight of this relay is based on a threshold of 3 or more + * measurements by Tor bandwidth authorities. Omitted if the network status consensus containing this + * relay does not contain measurement information. + */ + measured?: boolean; + /** + * Array of IPv4 or IPv6 addresses and TCP ports or port lists where the relay claims in its descriptor to + * accept onion-routing connections but that the directory authorities failed to confirm as reachable. + * Contains only additional addresses of a relay that are found unreachable and only as long as a minority of + * directory authorities performs reachability tests on these additional addresses. Relays with an unreachable + * primary address are not included in the network status consensus and excluded entirely. Likewise, relays + * with unreachable additional addresses tested by a majority of directory authorities are not included in + * the network status consensus and excluded here, too. If at any point network status votes will be added + * to the processing, relays with unreachable addresses will be included here. Addresses are in arbitrary order. + * IPv6 hex characters are all lower-case. Omitted if empty. + */ + unreachable_or_addresses?: string[]; + } + + interface BridgeSummary { + /** + * Bridge nickname consisting of 1–19 alphanumerical characters. + */ + n: string; + /** + * SHA-1 hash of the bridge fingerprint consisting of 40 upper-case hexadecimal characters. + */ + h: string; + /** + * Boolean field saying whether this bridge was listed as running in the last bridge network status. + */ + r: boolean; + } + + interface Bridge { + /** + * Bridge nickname consisting of 1–19 alphanumerical characters. + */ + nickname: string; + /** + * SHA-1 hash of the bridge fingerprint consisting of 40 upper-case hexadecimal characters. + */ + hashed_fingerprint: string; + /** + * Array of sanitized IPv4 or IPv6 addresses and TCP ports or port lists where the bridge accepts + * onion-routing connections. The first address is the primary onion-routing address that the bridge used + * to register in the network, subsequent addresses are in arbitrary order. IPv6 hex characters are all lower-case. + * Sanitized IP addresses are always in `10/8` or `[fd9f:2e19:3bcf/48]` IP networks and are only useful + * to learn which IP version the bridge uses and to detect whether the bridge changed its address. + * Sanitized IP addresses always change on the 1st of every month at 00:00:00 UTC, regardless of the bridge + * actually changing its IP address. TCP ports are not sanitized. + */ + or_addresses: string[]; + /** + * UTC timestamp (YYYY-MM-DD hh:mm:ss) when this bridge was last seen in a bridge network status. + */ + last_seen: string; + /** + * UTC timestamp (YYYY-MM-DD hh:mm:ss) when this bridge was first seen in a bridge network status. + */ + first_seen: string; + /** + * Boolean field saying whether this bridge was listed as running in the last bridge network status. + */ + running: boolean; + /** + * Array of relay flags that the bridge authority assigned to this bridge. May be omitted if empty. + */ + flags?: string[]; + /** + * UTC timestamp (YYYY-MM-DD hh:mm:ss) when the bridge was last (re-)started. + * Missing if router descriptor containing this information cannot be found. + */ + last_restarted?: string; + /** + * Bandwidth in bytes per second that this bridge is willing and capable to provide. This bandwidth value + * is the minimum of `bandwidth_rate`, `bandwidth_burst`, and `observed_bandwidth`. + * Missing if router descriptor containing this information cannot be found. + */ + advertised_bandwidth?: number; + /** + * Platform string containing operating system and Tor version details. + * Omitted if not provided by the bridge or if descriptor containing this information cannot be found. + */ + platform?: string; + /** + * Tor software version without leading "Tor" as reported by the bridge in the "platform" line of its server + * descriptor. Omitted if not provided by the bridge, if the descriptor containing this information cannot + * be found, or if the bridge runs an alternative Tor implementation. + */ + version?: string; + /** + * Boolean field saying whether the Tor software version of this bridge is recommended by the directory + * authorities or not. Uses the bridge version in the bridge network status. Omitted if either the directory + * authorities did not recommend versions, or the bridge did not report which version it runs. + */ + recommended_version?: boolean; + /** + * Status of the Tor software version of this bridge based on the versions recommended by the directory authorities. + * Possible version statuses are: `recommended` if a version is listed as recommended; `experimental` if a + * version is newer than every recommended version; `obsolete` if a version is older than every recommended version; + * `new in series` if a version has other recommended versions with the same first three components, and the + * version is newer than all such recommended versions, but it is not newer than every recommended version; + * `unrecommended` if none of the above conditions hold. Omitted if either the directory authorities did not + * recommend versions, or the bridge did not report which version it runs. + */ + version_status?: + | 'recommended' + | 'experimental' + | 'obsolete' + | 'new in series' + | 'unrecommended'; + /** + * Array of (pluggable) transport names supported by this bridge. + */ + transports?: string[]; + } + + interface NodeBandwidth { + /** + * Node fingerprint consisting of 40 upper-case hexadecimal characters. + */ + fingerprint: string; + /** + * Object containing graph history objects with written bytes for different time periods. Keys are string + * representation of the time period covered by the graph history object. Keys are fixed strings `3_days`, + * `1_week`, `1_month`, `6_months`, `1_year`, and `5_years`. Keys refer to the last known bandwidth history + * of a node, not to the time when the bandwidth document was published. A graph history object is only + * ontained if the time period it covers is not already contained in another graph history object with shorter + * time period and higher data resolution. Similarly, a graph history object is excluded if the node did not + * provide bandwidth histories on the required level of detail. The unit is bytes per second. Contained + * graph history objects may contain null values if the node did not provide any bandwidth data or only data + * for less than 20% of a given time period. + */ + write_history?: Partial< + Record<'3_days' | '1_week' | '1_month' | '6_months' | '1_year' | '5_years', Histogram> + >; + /** + * Object containing graph history objects with read bytes for different time periods. The specification + * of graph history objects is similar to those in the `write_history` field. + */ + read_history?: Partial< + Record<'3_days' | '1_week' | '1_month' | '6_months' | '1_year' | '5_years', Histogram> + >; + } + + interface RelayWeights { + /** + * Node fingerprint consisting of 40 upper-case hexadecimal characters. + */ + fingerprint: string; + /** + * History object containing the fraction of this relay's consensus weight compared to the sum of all consensus + * weights in the network. This fraction is a very rough approximation of the probability of this relay to be + * selected by clients. Keys are string representation of the time period covered by the graph history object. + * Keys are fixed strings `1_week`, `1_month`, `6_months`, `1_year`, and `5_years`. Keys refer to the last known + * weights history of a relay, not to the time when the weights document was published. A graph history object is + * only contained if the time period it covers is not already contained in another graph history object with shorter + * time period and higher data resolution. The unit is path-selection probability. Contained graph history objects + * may contain null values if the relay was running less than 20% of a given time period. + */ + consensus_weight_fraction?: Partial< + Record<'1_week' | '1_month' | '6_months' | '1_year' | '5_years', Histogram> + >; + /** + * History object containing the probability of this relay to be selected for the guard position. + * This probability is calculated based on consensus weights, relay flags, and bandwidth weights in the consensus. + * Path selection depends on more factors, so that this probability can only be an approximation. + * The specification of this history object is similar to that in the `consensus_weight_fraction` field above. + */ + guard_probability?: Partial< + Record<'1_week' | '1_month' | '6_months' | '1_year' | '5_years', Histogram> + >; + /** + * History object containing the probability of this relay to be selected for the middle position. + * This probability is calculated based on consensus weights, relay flags, and bandwidth weights in the consensus. + * Path selection depends on more factors, so that this probability can only be an approximation. + * The specification of this history object is similar to that in the `consensus_weight_fraction` field above. + */ + middle_probability?: Partial< + Record<'1_week' | '1_month' | '6_months' | '1_year' | '5_years', Histogram> + >; + /** + * History object containing the probability of this relay to be selected for the exit position. + * This probability is calculated based on consensus weights, relay flags, and bandwidth weights in the consensus. + * Path selection depends on more factors, so that this probability can only be an approximation. + * The specification of this history object is similar to that in the `consensus_weight_fraction` field above. + */ + exit_probability?: Partial< + Record<'1_week' | '1_month' | '6_months' | '1_year' | '5_years', Histogram> + >; + /** + * History object containing the absolute consensus weight of this relay. The specification of this history + * object is similar to that in the `consensus_weight_fraction` field above. + */ + consensus_weight?: Partial< + Record<'1_week' | '1_month' | '6_months' | '1_year' | '5_years', Histogram> + >; + } + + interface BridgeClients { + /** + * SHA-1 hash of the bridge fingerprint consisting of 40 upper-case hexadecimal characters. + */ + fingerprint: string; + /** + * Object containing graph history objects with the average number of clients connecting to this bridge. + * Keys are string representation of the time period covered by the graph history object. Keys are fixed strings + * `6_months`, `1_year`, and `5_years`. Keys refer to the last known clients history of a bridge, not to the time + * when the clients document was published. A graph history object is only contained if the time period it + * covers is not already contained in another clients graph object with shorter time period and higher + * data resolution. The unit is number of clients. Contained graph history objects may contain null values + * if the bridge did not report client statistics for at least 50% of a given time period. + */ + average_clients?: Partial>; + } + + interface RelayUptime { + /** + * Relay fingerprint consisting of 40 upper-case hexadecimal characters. + */ + fingerprint: string; + /** + * Object containing graph history objects with the fractional uptime of this relay. Keys are string + * representation of the time period covered by the graph history object. Keys are fixed strings + * `1_week`, `1_month`, `6_months`, `1_year`, and `5_years`. Keys refer to the last known uptime history + * of a relay, not to the time when the uptime document was published. A graph history object is only + * contained if the time period it covers is not already contained in another graph history object with + * shorter time period and higher data resolution. The unit is fractional uptime from `0` to `1`. + * Contained graph history objects may contain null values if less than 20% of network statuses have been + * processed for a given time period. + */ + uptime?: Partial< + Record<'1_week' | '1_month' | '6_months' | '1_year' | '5_years', Histogram> + >; + /** + * Object containing fractional times of this relay having relay flags assigned. Keys are flag names like + * `Running` or `Exit`, values are objects similar to the uptime field above, again with keys like + * `1_week` etc. If a relay never had a given relay flag assigned, no object is included for that flag. + */ + flags?: { + [key: string]: Partial< + Record<'1_week' | '1_month' | '6_months' | '1_year' | '5_years', Histogram> + >; + }; + } + + interface BridgeUptime { + /** + * SHA-1 hash of the bridge fingerprint consisting of 40 upper-case hexadecimal characters. + */ + fingerprint: string; + /** + * Object containing uptime history objects for different time periods. The specification of uptime history + * objects is similar to those in the `uptime` field of `RelayUptime`. + */ + uptime?: Partial< + Record<'1_week' | '1_month' | '6_months' | '1_year' | '5_years', Histogram> + >; + } + + interface Histogram { + first: string; + last: string; + interval: number; + factor: number; + count: number; + values: number[]; + } +} diff --git a/types/onionoo/onionoo-tests.ts b/types/onionoo/onionoo-tests.ts new file mode 100644 index 0000000000..10bf00900b --- /dev/null +++ b/types/onionoo/onionoo-tests.ts @@ -0,0 +1,38 @@ +import Onionoo = require('onionoo'); +import KeyvRedis = require('@keyv/redis'); + +const onionoo = new Onionoo(); +onionoo; // $ExpectType Instance & Endpoints + +const query = { + limit: 10, + running: true, + order: '-consensus_weight', +}; + +onionoo.summary(query).then(response => { + response.body; // $ExpectType Response + + const body = response.body; + + body.version; // $ExpectType string + body.relays_published; // $ExpectType string + body.relays; // $ExpectType RelaySummary[] + body.bridges_published; // $ExpectType string + body.bridges; // $ExpectType BridgeSummary[] +}); +onionoo.details(query); // $ExpectType GotPromise> +onionoo.bandwidth(query); // $ExpectType GotPromise> +onionoo.weights(query); // $ExpectType GotPromise> +onionoo.clients(query); // $ExpectType GotPromise> +onionoo.uptime(query); // $ExpectType GotPromise> + +// $ExpectType Instance & Partial +new Onionoo({ + baseUrl: 'https://onionoo.torproject.org', + endpoints: ['summary', 'details', 'bandwidth', 'weights', 'clients', 'uptime'], + cache: false, +}); + +new Onionoo({ cache: new Map() }); +new Onionoo({ cache: new KeyvRedis('redis://user:pass@localhost:6379') }); diff --git a/types/onionoo/tsconfig.json b/types/onionoo/tsconfig.json new file mode 100644 index 0000000000..d2b0560222 --- /dev/null +++ b/types/onionoo/tsconfig.json @@ -0,0 +1,28 @@ +{ + "compilerOptions": { + "module": "commonjs", + "lib": [ + "es6" + ], + "noImplicitAny": true, + "noImplicitThis": true, + "strictNullChecks": true, + "strictFunctionTypes": true, + "baseUrl": "../", + "typeRoots": [ + "../" + ], + "types": [], + "paths": { + "@keyv/redis": [ + "keyv__redis" + ] + }, + "noEmit": true, + "forceConsistentCasingInFileNames": true + }, + "files": [ + "index.d.ts", + "onionoo-tests.ts" + ] +} diff --git a/types/onionoo/tslint.json b/types/onionoo/tslint.json new file mode 100644 index 0000000000..3db14f85ea --- /dev/null +++ b/types/onionoo/tslint.json @@ -0,0 +1 @@ +{ "extends": "dtslint/dt.json" }