pub struct Client(/* private fields */);Expand description
A client for the InternetData API.
Cloning is cheap and shares everything, including the cache and the connection pool, so a clone per task is the intended way to use it across one.
The cache is per instance and never global: two clients holding different API keys are on different plans and entitled to different fields, so a shared cache would serve one of them the other’s shape.
Implementations§
Source§impl Client
impl Client
Sourcepub fn new() -> Result<Self, Error>
pub fn new() -> Result<Self, Error>
A client with no API key, against production. Without a key a lookup is
on Unlimited, the free plan, limited per address per minute. A batch
needs a paid plan, and Client::my_entitlement and every database
published today need a key.
pub fn builder() -> ClientBuilder
Sourcepub async fn lookup(&self, ip: &str) -> Result<Lookup, Error>
pub async fn lookup(&self, ip: &str) -> Result<Lookup, Error>
What every database says about one address.
A bogon is answered locally and never reaches the network. Everything
else is served, then cached for this client. Calls that miss the cache
while a request for their address is in flight, a batch’s included, await
that request rather than sending their own. An IPv4-mapped address
(::ffff:8.8.8.8) is the IPv4 address it carries: judged, sent and cached
as that, so the answer names 8.8.8.8.
Anything but an IP address is refused as a bad request before it is sent:
the API answers an AS or a domain at the same path, in a shape this call
cannot read, so ask Client::lookup_asn or Client::lookup_domain.
Sourcepub async fn lookup_with(
&self,
ip: &str,
opts: LookupOptions,
) -> Result<Lookup, Error>
pub async fn lookup_with( &self, ip: &str, opts: LookupOptions, ) -> Result<Lookup, Error>
Client::lookup, with this call’s own retry budget and timeout. A call
that joins a request already in flight takes that request’s answer, sent
under the options of the call that led it.
Sourcepub async fn my_ip(&self) -> Result<Lookup, Error>
pub async fn my_ip(&self) -> Result<Lookup, Error>
What every database says about the address this client is calling from.
The same answer Client::lookup would give for that address, at the
same cost against your allowance. The address is the one our edge
observed, so a call made through a proxy or a VPN reports the exit it
left through - usually the point of asking.
Deliberately NOT cached. The cache is keyed by address, and which address this is IS the question: a machine that moves between networks would otherwise be told where it used to be.
Sourcepub async fn my_ip_with(&self, opts: LookupOptions) -> Result<Lookup, Error>
pub async fn my_ip_with(&self, opts: LookupOptions) -> Result<Lookup, Error>
Client::my_ip, with this call’s own retry budget and timeout.
Sourcepub async fn my_entitlement(&self) -> Result<Entitlement, Error>
pub async fn my_entitlement(&self) -> Result<Entitlement, Error>
What this client’s key is entitled to, and how much of it has been used.
Named for what it answers rather than me, which sits one letter from
Client::my_ip and means something quite different: one is which
address you are calling FROM, the other is what the key you are calling
WITH may spend.
Unlike a lookup there is no useful unauthenticated answer, so a client built without an API key gets an unauthorized error rather than a partial one.
Usage counts against the ALLOWANCE WINDOW - on a paid plan the anniversary of the subscription, not the calendar month and not the billing period, and on the free plan the UTC day - and it is the same number a lookup is gated on. It can lag by a few seconds, because requests are counted in memory and flushed in aggregate.
Deliberately NOT cached: the whole point is what has been spent, and a cached answer is a wrong one within seconds of the next request.
Sourcepub async fn my_entitlement_with(
&self,
opts: LookupOptions,
) -> Result<Entitlement, Error>
pub async fn my_entitlement_with( &self, opts: LookupOptions, ) -> Result<Entitlement, Error>
Client::my_entitlement, with this call’s own retry budget and timeout.
Sourcepub async fn lookup_batch<I, S>(
&self,
ips: I,
opts: BatchOptions,
) -> IndexMap<String, Result<Lookup, Error>>
pub async fn lookup_batch<I, S>( &self, ips: I, opts: BatchOptions, ) -> IndexMap<String, Result<Lookup, Error>>
Looks many addresses up in as few requests as possible.
Bogons are answered locally and cached answers are reused, and an address
with a request already in flight, a single lookup’s or another batch’s,
awaits that request; everything else goes to POST /batch in chunks of up
to 1000 addresses, with at most concurrency chunks in flight. The answers are keyed by address
rather than positional, so duplicates in the input collapse to a single
entry and the caller never has to line two lists up. Keys are in the
order the addresses were first seen. An address that fails carries its
error as its value, so one bad entry cannot lose the rest of the answers:
the API reports a per-entry failure with the status the single lookup
would have answered, and a chunk that fails as a whole marks every
address in it. POST /batch needs a paid plan: without a key every
address in a request of two or more carries an unauthorized error, and
a free-plan key’s request of two or more a bad request (HTTP 402). A
request of one address is answered as its lookup would be.
Sourcepub async fn lookup_asn(&self, asn: u32) -> Result<AsnLookupResponse, Error>
pub async fn lookup_asn(&self, asn: u32) -> Result<AsnLookupResponse, Error>
What every database says about one AS.
Sent as given and never cached: the cache is keyed by address, and an AS answer has none. Nor is it batched, so many AS numbers are many calls.
Sourcepub async fn lookup_asn_with(
&self,
asn: u32,
opts: LookupOptions,
) -> Result<AsnLookupResponse, Error>
pub async fn lookup_asn_with( &self, asn: u32, opts: LookupOptions, ) -> Result<AsnLookupResponse, Error>
Client::lookup_asn, with this call’s own retry budget and timeout.
Sourcepub async fn lookup_domain(
&self,
domain: &str,
) -> Result<DomainLookupResponse, Error>
pub async fn lookup_domain( &self, domain: &str, ) -> Result<DomainLookupResponse, Error>
What every database says about one domain.
Sent as given, escaped into the path: the API reads it lowercase and in
punycode, and refuses what it cannot read as a bad request. Never cached,
and not batched, as Client::lookup_asn is not.
Sourcepub async fn lookup_domain_with(
&self,
domain: &str,
opts: LookupOptions,
) -> Result<DomainLookupResponse, Error>
pub async fn lookup_domain_with( &self, domain: &str, opts: LookupOptions, ) -> Result<DomainLookupResponse, Error>
Client::lookup_domain, with this call’s own retry budget and timeout.
Sourcepub fn is_bogon(&self, ip: &str) -> bool
pub fn is_bogon(&self, ip: &str) -> bool
Whether an address is answered locally rather than served. Exposed here
so the check is reachable from the client you already hold; the free
crate::is_bogon is the same function.
Sourcepub fn database(&self) -> DatabaseApi<'_>
pub fn database(&self) -> DatabaseApi<'_>
The database catalog and its downloads.
They hang off here rather than off the client itself, which is where the sibling VPNDetection crate keeps the same calls, so one program holding both spells the two the same way.
Sourcepub fn oauth(&self) -> OauthApi<'_>
pub fn oauth(&self) -> OauthApi<'_>
Signing a person in with OAuth: the device flow, so a program on their
own machine can be handed one of their API keys, or the authorization
code flow, for an app that can take a browser redirect. These requests
never carry this client’s API key, so a client built without one works,
and they go to the apex, which OauthApi says how it is found.