vhad/DefinitelyTyped
1
0
Fork 0
mirror of https://github.com/gosticks/DefinitelyTyped.git synced 2026-06-28 22:30:01 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

[onionoo] Add types

Browse Source
This commit is contained in:
Dimitri Benin
2019-02-01 16:47:51 +01:00
parent ebd68eecb9
commit daa82adb11
4 changed files with 887 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

820
types/onionoo/index.d.ts vendored Normal file
View File

@@ -0,0 +1,820 @@
// Type definitions for onionoo 2.0
// Project: https://github.com/lukechilds/onionoo-node-client
// Definitions by: BendingBender <https://github.com/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<Onionoo.Endpoints>;
}
declare namespace Onionoo {
interface Instance {
get(endpoint: 'summary', query?: QueryParameters): GotPromise<Summary>;
get(endpoint: 'details', query?: QueryParameters): GotPromise<Details>;
get(endpoint: 'bandwidth', query?: QueryParameters): GotPromise<Bandwidth>;
get(endpoint: 'weights', query?: QueryParameters): GotPromise<Weights>;
get(endpoint: 'clients', query?: QueryParameters): GotPromise<Clients>;
get(endpoint: 'uptime', query?: QueryParameters): GotPromise<Uptime>;
}
interface Endpoints {
summary(query?: QueryParameters): GotPromise<Summary>;
details(query?: QueryParameters): GotPromise<Details>;
bandwidth(query?: QueryParameters): GotPromise<Bandwidth>;
weights(query?: QueryParameters): GotPromise<Weights>;
clients(query?: QueryParameters): GotPromise<Clients>;
uptime(query?: QueryParameters): GotPromise<Uptime>;
}
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<RelaySummary, BridgeSummary>;
type Details = Response<Relay, Bridge>;
type Bandwidth = Response<NodeBandwidth, NodeBandwidth>;
type Weights = Response<RelayWeights, undefined>;
type Clients = Response<undefined, BridgeClients>;
type Uptime = Response<RelayUptime, BridgeUptime>;
interface Response<TRelay, TBridge> {
/**
* 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<Record<'6_months' | '1_year' | '5_years', Histogram>>;
}
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[];
}
}

38
types/onionoo/onionoo-tests.ts Normal file
View File

@@ -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<RelaySummary, BridgeSummary>
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<Response<Relay, Bridge>>
onionoo.bandwidth(query); // $ExpectType GotPromise<Response<NodeBandwidth, NodeBandwidth>>
onionoo.weights(query); // $ExpectType GotPromise<Response<RelayWeights, undefined>>
onionoo.clients(query); // $ExpectType GotPromise<Response<undefined, BridgeClients>>
onionoo.uptime(query); // $ExpectType GotPromise<Response<RelayUptime, BridgeUptime>>
// $ExpectType Instance & Partial<Endpoints>
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') });

28
types/onionoo/tsconfig.json Normal file
View File

@@ -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"
]
}

1
types/onionoo/tslint.json Normal file
View File

@@ -0,0 +1 @@
{ "extends": "dtslint/dt.json" }