Skip to main content

Client

Struct Client 

Source
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

Source

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.

Source

pub fn builder() -> ClientBuilder

Source

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.

Source

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.

Source

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.

Source

pub async fn my_ip_with(&self, opts: LookupOptions) -> Result<Lookup, Error>

Client::my_ip, with this call’s own retry budget and timeout.

Source

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.

Source

pub async fn my_entitlement_with( &self, opts: LookupOptions, ) -> Result<Entitlement, Error>

Client::my_entitlement, with this call’s own retry budget and timeout.

Source

pub async fn lookup_batch<I, S>( &self, ips: I, opts: BatchOptions, ) -> IndexMap<String, Result<Lookup, Error>>
where I: IntoIterator<Item = S>, S: AsRef<str>,

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Trait Implementations§

Source§

impl Clone for Client

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for Client

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl !RefUnwindSafe for Client

§

impl !UnwindSafe for Client

§

impl Forget for Client

§

impl Freeze for Client

§

impl Move for Client

§

impl Send for Client

§

impl Sync for Client

§

impl Unpin for Client

§

impl UnsafeUnpin for Client

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Pointable for T

Source§

const ALIGN: usize

The alignment of pointer.
Source§

type Init = T

The type for initializers.
Source§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
Source§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
Source§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
Source§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
Source§

impl<T> PolicyExt for T
where T: ?Sized,

Source§

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow only if self and other return Action::Follow. Read more
Source§

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow if either self or other returns Action::Follow. Read more
Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more