Documentation
¶
Overview ¶
Package internetdata is the official Go client library for the InternetData API: what every InternetData database says about an IP address, an AS or a domain, and the licensed databases themselves, downloaded as CSV.GZ or MMDB.
Start with New and Client.Lookup. No API key is needed: without one a lookup is on Unlimited, the free plan, limited per address per minute. A batch needs a paid plan, and Client.Database a key carrying the db.download scope.
Index ¶
- Constants
- Variables
- func BoolValue(v *bool) bool
- func IsBogon(ip string) bool
- type AbuseContact
- type Asn
- type AsnHostedDomains
- type AsnLookupResponse
- type AsnPrefix
- type AuthorizationURLOptions
- type BatchOption
- type BatchResult
- type BitTorrentDetail
- type BuildDownloads
- func (b *BuildDownloads) Download(ctx context.Context, id string, format Format, dst io.Writer) (int64, error)
- func (b *BuildDownloads) DownloadBytes(ctx context.Context, id string, format Format) ([]byte, error)
- func (b *BuildDownloads) DownloadFile(ctx context.Context, id string, format Format, path string) (int64, error)
- func (b *BuildDownloads) DownloadURL(ctx context.Context, id string, format Format) (string, error)
- type CarrierDetail
- type Checksums
- type ClassDetail
- type Client
- func (c *Client) IsBogon(ip string) bool
- func (c *Client) Lookup(ctx context.Context, ip string, opts ...LookupOption) (*Result, error)
- func (c *Client) LookupASN(ctx context.Context, asn uint32, opts ...LookupOption) (*AsnLookupResponse, error)
- func (c *Client) LookupBatch(ctx context.Context, ips []string, opts ...BatchOption) (map[string]BatchResult, error)
- func (c *Client) LookupDomain(ctx context.Context, domain string, opts ...LookupOption) (*DomainLookupResponse, error)
- func (c *Client) MyEntitlement(ctx context.Context, opts ...LookupOption) (*Entitlement, error)
- func (c *Client) MyIP(ctx context.Context, opts ...LookupOption) (*Result, error)
- type ClientRegistration
- type Company
- type DNSAddressRecord
- type DNSCnameRecord
- type DNSMxRecord
- type DNSNsRecord
- type DNSResolverDetail
- type Database
- type DatabaseAPI
- func (d *DatabaseAPI) AtBuild(name string) *BuildDownloads
- func (d *DatabaseAPI) Checksums(ctx context.Context, id string, format Format) (*Checksums, error)
- func (d *DatabaseAPI) Download(ctx context.Context, id string, format Format, dst io.Writer) (int64, error)
- func (d *DatabaseAPI) DownloadBytes(ctx context.Context, id string, format Format) ([]byte, error)
- func (d *DatabaseAPI) DownloadFile(ctx context.Context, id string, format Format, path string) (int64, error)
- func (d *DatabaseAPI) DownloadURL(ctx context.Context, id string, format Format) (string, error)
- func (d *DatabaseAPI) Downloads(ctx context.Context, limit int) ([]DownloadAttempt, error)
- func (d *DatabaseAPI) List(ctx context.Context) ([]Database, error)
- func (d *DatabaseAPI) Metadata(ctx context.Context, id string) (*DatabaseMetadata, error)
- type DatabaseMetadata
- type DatabaseMetadataColumn
- type DatabaseVersion
- type Date
- type DeviceAuthorization
- type DeviceAuthorizationOptions
- type DisposableDetail
- type DomainDNS
- type DomainIPRange
- type DomainIPRanges
- type DomainLookupResponse
- type DownloadAttempt
- type DownloadOutcome
- type Entitlement
- type EntitlementApikey
- type EntitlementPlan
- type EntitlementUsage
- type Error
- type ErrorKind
- type Format
- type HostedDomains
- type LicenseType
- type Location
- type LookupOption
- type LookupResponse
- type OauthAPI
- func (o *OauthAPI) AuthorizationURL(clientID, redirectURI, codeChallenge string, opts AuthorizationURLOptions) (string, error)
- func (o *OauthAPI) CreatePkce() Pkce
- func (o *OauthAPI) DeviceAuthorization(ctx context.Context, clientID string, opts DeviceAuthorizationOptions) (*DeviceAuthorization, error)
- func (o *OauthAPI) ExchangeAuthorizationCode(ctx context.Context, clientID, code, codeVerifier, redirectURI string) (*TokenResponse, error)
- func (o *OauthAPI) ExchangeDeviceCode(ctx context.Context, clientID, deviceCode string) (*TokenResponse, error)
- func (o *OauthAPI) ExchangeRefreshToken(ctx context.Context, clientID, refreshToken string) (*TokenResponse, error)
- func (o *OauthAPI) Metadata(ctx context.Context) (*OauthMetadata, error)
- func (o *OauthAPI) PkceChallenge(verifier string) string
- func (o *OauthAPI) PollDeviceToken(ctx context.Context, clientID string, device *DeviceAuthorization) (*TokenResponse, error)
- func (o *OauthAPI) Register(ctx context.Context, redirectURIs []string, opts RegisterOptions) (*ClientRegistration, error)
- func (o *OauthAPI) Revoke(ctx context.Context, clientID, token string) error
- type OauthError
- type OauthMetadata
- type Option
- type Pkce
- type ProxyDetail
- type PubproxyDetail
- type RegisterOptions
- type Result
- type Rwhois
- type SMTPDetail
- type SSHDetail
- type SatelliteDetail
- type Standing
- type TokenResponse
- type WebDetail
- type Whois
Constants ¶
const ( StandingLicensed = api.StandingLicensed StandingExpired = api.StandingExpired StandingUnlicensed = api.StandingUnlicensed )
Standing tells you whether a database is yours today, was, or has never been bought.
const ( LicenseTypeEvaluation = api.Evaluation LicenseTypeStandard = api.Standard LicenseTypeRedistribute = api.Redistribute )
LicenseType is nil rather than one of these when there is no license at all, so read the pointer before comparing it.
const ( DownloadOutcomeOK = api.DownloadOutcomeOk DownloadOutcomeDenied = api.DownloadOutcomeDenied DownloadOutcomeExpired = api.DownloadOutcomeExpired DownloadOutcomeUnknown = api.DownloadOutcomeUnknown )
const DefaultBaseURL = "https://api.internetdata.io"
DefaultBaseURL is the production API. Override it with WithBaseURL.
Variables ¶
var ( ErrOauthAccessDenied = errors.New("internetdata: the person denied the sign-in") ErrOauthExpiredToken = errors.New("internetdata: the sign-in code expired") )
The two refusals a device sign-in ends on, matched with errors.Is against what an OauthAPI call returns.
Functions ¶
func BoolValue ¶ added in v2.10.0
BoolValue returns the value of the bool pointer passed in, or false if the pointer is nil.
Go has no `??`, so this is how a caller who only wants to know whether an address is flagged reads a tier-gated member: BoolValue(r.IsVpn). Read the pointer itself wherever absent and false must be told apart, which is the whole reason these are pointers. Same name and behavior as stripe-go's helper of the same name, so it should already be familiar.
func IsBogon ¶ added in v2.10.0
IsBogon reports whether an address is private, loopback, link-local, documentation, multicast or otherwise not routable on the public internet, including the IPv6 equivalents and the 6to4 and Teredo ranges that wrap them.
The API answers each with every flag false and every key empty, so the client answers them itself and they never cost a request. Client.IsBogon is the same check, for code that already holds a client. An IPv4-mapped address (::ffff:8.8.8.8) is judged as the IPv4 address it carries.
Types ¶
type AbuseContact ¶ added in v2.10.0
type AbuseContact = api.AbuseContact
The wire shapes a lookup answers with, re-exported so a consumer never has to name an internal package.
type Asn ¶ added in v2.10.0
Asn is the AS announcing the address, on every answer, with or without a key: Asn is 0 where none does.
type AsnHostedDomains ¶ added in v2.13.0
type AsnHostedDomains = api.AsnHostedDomains
The wire shapes a lookup answers with, re-exported so a consumer never has to name an internal package.
type AsnLookupResponse ¶ added in v2.10.0
type AsnLookupResponse = api.AsnLookupResponse
AsnLookupResponse is what LookupASN answers.
type AsnPrefix ¶ added in v2.10.0
The wire shapes a lookup answers with, re-exported so a consumer never has to name an internal package.
type AuthorizationURLOptions ¶ added in v2.5.0
type AuthorizationURLOptions struct {
// Scope is one space-delimited string, sent as given. The server narrows it
// to what the client may ask for.
Scope string
// State comes back on the redirect unchanged, so the caller can tell the
// answer is to its own request.
State string
// Resource is the API the tokens are meant for.
Resource string
}
AuthorizationURLOptions is what an authorization URL asks for beyond what every one carries. An empty field is left out of the URL.
type BatchOption ¶ added in v2.10.0
type BatchOption interface {
// contains filtered or unexported methods
}
BatchOption overrides a client default for one batch. Options that only mean something for a batch are BatchOption alone, so passing one to Lookup does not compile rather than being accepted and ignored.
func Concurrency ¶ added in v2.10.0
func Concurrency(n int) BatchOption
Concurrency overrides the client's in-flight limit for this batch - how many chunks of up to 1000 addresses are sent at once - so one large batch does not need a second client to widen it.
type BatchResult ¶ added in v2.10.0
BatchResult is one address's outcome within a batch. Exactly one of Result and Err is set.
type BitTorrentDetail ¶ added in v2.10.0
type BitTorrentDetail = api.BitTorrentDetail
The wire shapes a lookup answers with, re-exported so a consumer never has to name an internal package.
type BuildDownloads ¶ added in v2.9.1
type BuildDownloads struct {
// contains filtered or unexported fields
}
BuildDownloads downloads the build AtBuild named, with the same four methods and signatures as DatabaseAPI.
func (*BuildDownloads) Download ¶ added in v2.9.1
func (b *BuildDownloads) Download( ctx context.Context, id string, format Format, dst io.Writer, ) (int64, error)
Download is DatabaseAPI.Download for this build.
func (*BuildDownloads) DownloadBytes ¶ added in v2.9.1
func (b *BuildDownloads) DownloadBytes(ctx context.Context, id string, format Format) ([]byte, error)
DownloadBytes is DatabaseAPI.DownloadBytes for this build.
func (*BuildDownloads) DownloadFile ¶ added in v2.9.1
func (b *BuildDownloads) DownloadFile( ctx context.Context, id string, format Format, path string, ) (int64, error)
DownloadFile is DatabaseAPI.DownloadFile for this build.
func (*BuildDownloads) DownloadURL ¶ added in v2.9.1
DownloadURL is DatabaseAPI.DownloadURL for this build.
type CarrierDetail ¶ added in v2.10.0
type CarrierDetail = api.CarrierDetail
The wire shapes a lookup answers with, re-exported so a consumer never has to name an internal package.
type Checksums ¶
type Checksums struct {
MD5 string `json:"md5"`
SHA1 string `json:"sha1"`
SHA256 string `json:"sha256"`
SHA512 string `json:"sha512"`
}
Checksums are the digests of one published file.
Spelled out rather than aliased to the generated struct, whose Md5 and Sha256 are not the names a Go caller expects, and which every other InternetData and VPNDetection SDK writes the same way.
type ClassDetail ¶ added in v2.10.0
type ClassDetail = api.ClassDetail
The wire shapes a lookup answers with, re-exported so a consumer never has to name an internal package.
type Client ¶
type Client struct {
// Database is the licensed database catalog and its downloads, for keys
// that carry the db.download scope. Every database call hangs off it, which
// is how the VPNDetection SDKs read too, so one program holding both
// clients spells the two the same way.
Database *DatabaseAPI
// Oauth is the device sign-in, which hands a program one of a person's API
// keys. Its requests never carry this client's key.
Oauth *OauthAPI
// contains filtered or unexported fields
}
Client is a client for the InternetData API. It is safe for concurrent use.
The address lookups are cached per instance and never globally: 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. Nothing else is cached: what your organization may see depends on the key, so a listing held from one client is not an answer for another.
func (*Client) IsBogon ¶ added in v2.10.0
IsBogon reports whether an address is answered locally rather than served. Exposed here so the check is reachable from the client you already hold; the package-level IsBogon is the same function.
func (*Client) Lookup ¶ added in v2.10.0
Lookup answers what InternetData knows about one address.
A bogon is answered locally and never reaches the network. Everything else is served, then cached for this client. Treat the answer as read only: repeat lookups of one address hand back the same cached pointers.
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, and take its answer, sent under the options of the call that led it. The request runs detached from any one caller's context, so a caller giving up fails nobody else: it returns at once, and the answer is cached for the next.
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 before sending, as a bad_request: the API answers an AS or a domain at the same path, in a shape this call cannot read, so LookupASN and LookupDomain are how to ask for those.
func (*Client) LookupASN ¶ added in v2.10.0
func (c *Client) LookupASN( ctx context.Context, asn uint32, opts ...LookupOption, ) (*AsnLookupResponse, error)
LookupASN answers what InternetData knows about one autonomous system: its registration on every plan, and on a paid one its ASN Whois record and the prefixes it announces. The number is sent as given, and an AS no database knows is answered with empty values.
Not cached, and not batched: the cache and the batch are for addresses.
func (*Client) LookupBatch ¶ added in v2.10.0
func (c *Client) LookupBatch( ctx context.Context, ips []string, opts ...BatchOption, ) (map[string]BatchResult, error)
LookupBatch 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 Lookup's or another batch's, awaits that request; whatever is left goes to POST /batch in chunks of up to 1000, with at most `concurrency` chunks in flight, and a Lookup arriving meanwhile awaits this batch's answer for its address. 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. 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 a KindUnauthorized error, and a free-plan key's request of two or more a KindBadRequest (HTTP 402). A request of one address is answered as its lookup would be. The returned error is reserved for the batch as a whole failing: the context canceled, or a Concurrency below 1 or negative Retries, refused before any request.
func (*Client) LookupDomain ¶ added in v2.10.0
func (c *Client) LookupDomain( ctx context.Context, domain string, opts ...LookupOption, ) (*DomainLookupResponse, error)
LookupDomain answers what InternetData knows about one domain: on every plan whether it is registered and which DNS record types it has, and on a paid one the records themselves, its organization's IP ranges and whether it is a disposable email domain. The domain is sent as given, path-escaped; the API normalizes it and refuses one it cannot read as a bad_request.
Not cached, and not batched: the cache and the batch are for addresses.
func (*Client) MyEntitlement ¶ added in v2.10.0
func (c *Client) MyEntitlement(ctx context.Context, opts ...LookupOption) (*Entitlement, error)
MyEntitlement reports 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 MyIP 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 a key gets an unauthorized error rather than a partial one.
Usage is counted 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 the number is the same one 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.
func (*Client) MyIP ¶ added in v2.10.0
MyIP looks up the address this client is calling from.
The answer is the one Lookup would give for that address, and it costs the same 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 rather than the machine that made it - usually the point of asking.
Deliberately NOT cached. The cache is keyed by address, and the whole question here is which address that is: a laptop that moves between networks would otherwise be told where it used to be.
type ClientRegistration ¶ added in v2.8.0
type ClientRegistration struct {
// ClientID is the client ID for AuthorizationURL and ExchangeAuthorizationCode.
ClientID string `json:"client_id"`
// ClientIDIssuedAt is when it was issued, in Unix seconds.
ClientIDIssuedAt int64 `json:"client_id_issued_at"`
// ClientName is the name the person will see, a placeholder when none was
// given or none can be shown.
ClientName string `json:"client_name"`
RedirectURIs []string `json:"redirect_uris"`
GrantTypes *[]string `json:"grant_types,omitempty"`
ResponseTypes *[]string `json:"response_types,omitempty"`
// TokenEndpointAuthMethod is always none.
TokenEndpointAuthMethod string `json:"token_endpoint_auth_method"`
// Scope is the most this client may be granted.
Scope *string `json:"scope,omitempty"`
}
ClientRegistration is a registered client, public and with no secret: it proves each sign-in with PKCE. An optional member the server did not send is nil.
type Company ¶ added in v2.10.0
The wire shapes a lookup answers with, re-exported so a consumer never has to name an internal package.
type DNSAddressRecord ¶ added in v2.10.0
type DNSAddressRecord = api.DNSAddressRecord
The wire shapes a lookup answers with, re-exported so a consumer never has to name an internal package.
type DNSCnameRecord ¶ added in v2.10.0
type DNSCnameRecord = api.DNSCnameRecord
The wire shapes a lookup answers with, re-exported so a consumer never has to name an internal package.
type DNSMxRecord ¶ added in v2.10.0
type DNSMxRecord = api.DNSMxRecord
The wire shapes a lookup answers with, re-exported so a consumer never has to name an internal package.
type DNSNsRecord ¶ added in v2.10.0
type DNSNsRecord = api.DNSNsRecord
The wire shapes a lookup answers with, re-exported so a consumer never has to name an internal package.
type DNSResolverDetail ¶ added in v2.10.0
type DNSResolverDetail = api.DNSResolverDetail
The wire shapes a lookup answers with, re-exported so a consumer never has to name an internal package.
type Database ¶
Database is one database FAMILY, with your organization's license beside it. LicenseType, Starts and Expires are nil when there is no license.
type DatabaseAPI ¶
type DatabaseAPI struct {
// contains filtered or unexported fields
}
DatabaseAPI is the licensed database catalog and its downloads, reached through Client.Database.
Spelled DatabaseAPI rather than Database because Database is already this API's own shape for one database family, and it is what the other InternetData SDKs call this type.
func (*DatabaseAPI) AtBuild ¶ added in v2.9.1
func (d *DatabaseAPI) AtBuild(name string) *BuildDownloads
AtBuild is the four download calls for one build of each database, by the name a database.updated webhook gives it ("20261105.0t53s5"), so the file is the one whose sha256 the webhook carries; DatabaseAPI's own fetch the build that is live, as does an empty name. A build is kept 7 days; past that the call fails as KindBadRequest with the message BUILD_GONE, sent once.
func (*DatabaseAPI) Checksums ¶
Checksums are the digests of one published file, for verifying a download. All four the exporter writes are returned, because which of them a caller wants is not this library's decision.
func (*DatabaseAPI) Download ¶
func (d *DatabaseAPI) Download(ctx context.Context, id string, format Format, dst io.Writer) (int64, error)
Download streams one database file into dst and returns the bytes written.
Nothing beyond a single chunk is ever held in memory, whatever the file weighs. The transfer takes its deadline from ctx rather than from the HTTP client's Timeout, which would cap the whole body: 30 seconds is a sane bound on a catalog read and the wrong one on a gigabyte.
A failure DURING the transfer is returned as it happened rather than wrapped in an *Error: a reset socket and a full disk are different problems, and only one of them is ours.
func (*DatabaseAPI) DownloadBytes ¶
DownloadBytes downloads one database file and hands back its bytes.
This holds the ENTIRE file in memory, and the catalog spans five orders of magnitude, from bogon_asn_v1 at a few hundred bytes to the largest IP feeds at several gigabytes. Metadata publishes a Size per format; read it first, or use Download or DownloadFile for anything you have not measured.
func (*DatabaseAPI) DownloadFile ¶
func (d *DatabaseAPI) DownloadFile( ctx context.Context, id string, format Format, path string, ) (int64, error)
DownloadFile writes one database file to path and returns the bytes written.
The bytes land in a neighboring .part file that is renamed on completion, so a transfer that dies half way leaves no truncated file that reads as a whole database, and a failed refresh cannot destroy the copy already there. Otherwise identical to Download.
func (*DatabaseAPI) DownloadURL ¶
DownloadURL is the time-limited URL for one database file.
The API answers 302 to object storage and the redirect is NOT followed: the URL is returned so a caller can decide how to transfer a file that runs to gigabytes, hand it to a downloader, or pass it on without passing on the API key. The link is presigned and so authorizes itself. It only has to be valid when a transfer starts, so one already running isn't cut off when it lapses.
func (*DatabaseAPI) Downloads ¶
func (d *DatabaseAPI) Downloads(ctx context.Context, limit int) ([]DownloadAttempt, error)
Downloads is your organization's recent download attempts, newest first. A limit of zero or less takes the API's own default of 50, and it is clamped to 200.
Refusals are listed too: a denial is what answers "it stopped working", and its absence answers nothing.
func (*DatabaseAPI) List ¶
func (d *DatabaseAPI) List(ctx context.Context) ([]Database, error)
List is the published catalog, with your organization's license beside each family. A license covers a family, while a download names one of its versions, so the IDs the download and checksum calls take come from Database.Versions.
This is the server's answer for this key, so a listing held from one key is not an answer for another.
func (*DatabaseAPI) Metadata ¶
func (d *DatabaseAPI) Metadata(ctx context.Context, id string) (*DatabaseMetadata, error)
Metadata is what is inside one database: its columns per format, sample rows, the row count and the byte size of each file. It carries Updated and Entries without downloading anything, so poll it to decide whether today's build is worth fetching, and read Size to budget a transfer before starting one.
One document describes every format the database is built in, which is why there is no format argument.
type DatabaseMetadata ¶
type DatabaseMetadata = api.DatabaseMetadata
DatabaseMetadata is the build document the exporter writes, served through unchanged.
type DatabaseMetadataColumn ¶
type DatabaseMetadataColumn = api.DatabaseMetadataColumn
DatabaseMetadataColumn is one column of one format's schema.
type DatabaseVersion ¶
type DatabaseVersion = api.DatabaseVersion
DatabaseVersion is one published version of a family. Its ID is what the download, checksum and metadata calls take. Old versions are frozen rather than migrated, so both stay downloadable.
type DeviceAuthorization ¶ added in v2.3.0
type DeviceAuthorization struct {
DeviceCode string `json:"device_code"`
UserCode string `json:"user_code"`
VerificationURI string `json:"verification_uri"`
VerificationURIComplete *string `json:"verification_uri_complete,omitempty"`
ExpiresIn int `json:"expires_in"`
Interval int `json:"interval"`
}
DeviceAuthorization is a started device sign-in. ExpiresIn and Interval are seconds.
type DeviceAuthorizationOptions ¶ added in v2.3.0
type DeviceAuthorizationOptions struct {
// Scope is one space-delimited string, sent as given. The server narrows it
// to what the client may ask for.
Scope string
// Resource is the API the tokens are meant for.
Resource string
}
DeviceAuthorizationOptions narrows a device sign-in. An empty field is left out of the request rather than sent empty.
type DisposableDetail ¶ added in v2.10.0
type DisposableDetail = api.DisposableDetail
The wire shapes a lookup answers with, re-exported so a consumer never has to name an internal package.
type DomainDNS ¶ added in v2.10.0
The wire shapes a lookup answers with, re-exported so a consumer never has to name an internal package.
type DomainIPRange ¶ added in v2.10.0
type DomainIPRange = api.DomainIPRange
The wire shapes a lookup answers with, re-exported so a consumer never has to name an internal package.
type DomainIPRanges ¶ added in v2.10.0
type DomainIPRanges = api.DomainIPRanges
The wire shapes a lookup answers with, re-exported so a consumer never has to name an internal package.
type DomainLookupResponse ¶ added in v2.10.0
type DomainLookupResponse = api.DomainLookupResponse
DomainLookupResponse is what LookupDomain answers.
type DownloadAttempt ¶
DownloadAttempt is one entry of the download history, refusals included. Bytes is the object size at redirect time rather than bytes delivered: the transfer runs straight from object storage, so how much of it was taken is not observed.
type DownloadOutcome ¶
type DownloadOutcome = api.DownloadOutcome
DownloadOutcome is how one download attempt ended.
type Entitlement ¶ added in v2.10.0
type Entitlement = api.Entitlement
Entitlement is what a key is entitled to and what it has spent.
type EntitlementApikey ¶ added in v2.10.0
type EntitlementApikey = api.EntitlementApikey
EntitlementApikey is the credential itself. The key is never echoed back - only its ID, which is what the console shows.
type EntitlementPlan ¶ added in v2.10.0
type EntitlementPlan = api.EntitlementPlan
EntitlementPlan is the plan behind the key, and the field tier that decides how much of a lookup answer comes back.
type EntitlementUsage ¶ added in v2.10.0
type EntitlementUsage = api.EntitlementUsage
EntitlementUsage is consumption against the allowance.
type Error ¶
type Error struct {
Kind ErrorKind
// Message is the API's own explanation for a lookup and its result code for
// a database call, or a transport failure's text. The codes are
// deliberately not an enum on the wire, so one added later stays readable
// to a client built today.
Message string
// StatusCode is the HTTP status, or 0 when no response was received.
StatusCode int
// RetryAfter is how long the server asked us to wait. Zero when it did not
// ask, which on a 429 means an allowance is spent rather than throttled.
RetryAfter time.Duration
// contains filtered or unexported fields
}
Error is what every failure from this package unwraps to. Recover it with errors.As and branch on Kind.
type ErrorKind ¶
type ErrorKind string
ErrorKind says why a request failed.
KindRateLimited and KindQuotaExceeded both arrive as HTTP 429 and are NOT the same thing. A rate limit is the API protecting itself, carries Retry-After, and retrying works. A spent quota carries no such header and retrying will not help until the window rolls over or the limit is raised. The header is the only thing that distinguishes them.
type Format ¶
type Format string
Format is a format a database is published in. Not every one is built in every format: the _provider catalogs are keyed by provider ID rather than by IP range, so no MMDB exists for them, and asking for one is an error rather than an empty answer. DatabaseVersion.Formats says which exist.
func (Format) Valid ¶ added in v2.1.0
Valid reports whether f is a format the API publishes.
Format is a defined string type, so Format("zip") compiles: the constants above document the vocabulary without closing it. Callers taking a format from a flag, a config file or a model should check it here.
type HostedDomains ¶ added in v2.10.0
type HostedDomains = api.HostedDomains
The wire shapes a lookup answers with, re-exported so a consumer never has to name an internal package.
type LicenseType ¶
type LicenseType = api.DatabaseLicenseType
LicenseType is what a license permits you to do with the data.
type Location ¶ added in v2.10.0
Location is where the address is, on every answer, with or without a key. The members beyond the country and its currency are a paid plan's.
type LookupOption ¶ added in v2.10.0
type LookupOption interface {
BatchOption
// contains filtered or unexported methods
}
LookupOption overrides a client default for one call: Lookup, LookupASN, LookupDomain, MyIP, MyEntitlement or a batch, since every LookupOption works on a batch too.
func Retries ¶ added in v2.10.0
func Retries(n int) LookupOption
Retries overrides the client's retry count for this call. A negative count is refused with a bad_request *Error before anything answers the call, a bogon or a cached address included.
func Timeout ¶ added in v2.10.0
func Timeout(d time.Duration) LookupOption
Timeout overrides the HTTP client's Timeout for this call: 30 seconds unless WithHTTPClient supplied another. It replaces that bound rather than capping it, and like it bounds each ATTEMPT, so a retried call can take longer in total and ctx is what bounds the whole call. On a batch it bounds each chunk's request. Zero or less leaves an attempt unbounded, as on http.Client.
type LookupResponse ¶ added in v2.10.0
type LookupResponse = api.LookupResponse
The wire shapes a lookup answers with, re-exported so a consumer never has to name an internal package.
type OauthAPI ¶ added in v2.3.0
type OauthAPI struct {
// contains filtered or unexported fields
}
OauthAPI signs a person in on their own machine with the OAuth device flow, so a program can be handed one of their API keys instead of asking them to paste it, or through a browser redirect with the authorization code flow. Reached through Client.Oauth.
Every call takes a client ID, which is issued on request from support@internetdata.io. None of these requests carries the client's API key, and none needs one.
func (*OauthAPI) AuthorizationURL ¶ added in v2.5.0
func (o *OauthAPI) AuthorizationURL( clientID, redirectURI, codeChallenge string, opts AuthorizationURLOptions, ) (string, error)
AuthorizationURL is the URL to open in the person's browser for the authorization code flow. It makes no request. Once they decide, the server redirects to redirectURI with a code for ExchangeAuthorizationCode (and the state, when one was given), or with an error.
A required value that is empty or not UTF-8 is refused with a bad_request *Error.
func (*OauthAPI) CreatePkce ¶ added in v2.5.0
CreatePkce makes a fresh PKCE pair for one sign-in, from 32 bytes of the system's secure random source.
func (*OauthAPI) DeviceAuthorization ¶ added in v2.3.0
func (o *OauthAPI) DeviceAuthorization( ctx context.Context, clientID string, opts DeviceAuthorizationOptions, ) (*DeviceAuthorization, error)
DeviceAuthorization starts a device sign-in: show the person UserCode and VerificationURI, then hand the answer to PollDeviceToken. It consumes nothing, so it is retried like any read; a refusal such as slow_down comes back as an *OauthError.
func (*OauthAPI) ExchangeAuthorizationCode ¶ added in v2.5.0
func (o *OauthAPI) ExchangeAuthorizationCode( ctx context.Context, clientID, code, codeVerifier, redirectURI string, ) (*TokenResponse, error)
ExchangeAuthorizationCode trades the code a sign-in's redirect brought back for tokens. codeVerifier is the PKCE verifier whose challenge went into the authorization URL, and redirectURI that URL's, exactly.
Never retried: the server spends the code on first read, before it checks the verifier, so a retry could only be refused.
func (*OauthAPI) ExchangeDeviceCode ¶ added in v2.3.0
func (o *OauthAPI) ExchangeDeviceCode(ctx context.Context, clientID, deviceCode string) (*TokenResponse, error)
ExchangeDeviceCode asks once whether the person has approved a device sign-in. Until they do the answer is an *OauthError coded authorization_pending; PollDeviceToken is the loop around it.
Never retried: an approved code is spent by the answer that carries the tokens, so a retry after a lost response could only lose them.
func (*OauthAPI) ExchangeRefreshToken ¶ added in v2.3.0
func (o *OauthAPI) ExchangeRefreshToken( ctx context.Context, clientID, refreshToken string, ) (*TokenResponse, error)
ExchangeRefreshToken trades a refresh token for a new pair. The old one is spent whatever happens next, so this is never retried. A refresh names the API key the person picked (ApikeyID) but never reveals it again (Apikey).
func (*OauthAPI) Metadata ¶ added in v2.3.0
func (o *OauthAPI) Metadata(ctx context.Context) (*OauthMetadata, error)
Metadata is the authorization server's discovery document. Nothing else here needs it: every request is built from the client's base URL.
func (*OauthAPI) PkceChallenge ¶ added in v2.5.0
PkceChallenge is the S256 challenge for a PKCE verifier: its SHA-256, as unpadded base64url.
func (*OauthAPI) PollDeviceToken ¶ added in v2.3.0
func (o *OauthAPI) PollDeviceToken( ctx context.Context, clientID string, device *DeviceAuthorization, ) (*TokenResponse, error)
PollDeviceToken waits for the person to approve a device sign-in and returns its tokens.
It waits device.Interval seconds (5 when that is below 1) before EVERY request, the first included, and adds 5 more for the rest of the call each time the server answers slow_down. No wait runs past device.ExpiresIn, counted from this call: one that would ends at it, with no request after. It stops at the first answer that is neither pending nor slow_down: a denial satisfies errors.Is(err, ErrOauthAccessDenied), an expired code errors.Is(err, ErrOauthExpiredToken), and so does running out of device.ExpiresIn, with a StatusCode of 0. Canceling ctx stops the wait and any request in flight.
func (*OauthAPI) Register ¶ added in v2.8.0
func (o *OauthAPI) Register( ctx context.Context, redirectURIs []string, opts RegisterOptions, ) (*ClientRegistration, error)
Register registers a client for the authorization code flow, for a program that cannot serve a Client ID Metadata Document, and returns its ClientID.
Each redirect URI must be https on a public host name, or http on a loopback address, which then matches on any port; the server refuses any other with an *OauthError coded invalid_redirect_uri. Nothing is kept until a person approves the client, so registering again costs nothing, and this is retried like any read. No redirect URI at all, or one that is empty or not UTF-8, is refused with a bad_request *Error before anything is sent.
type OauthError ¶ added in v2.3.0
type OauthError struct {
// ErrorCode is the server's code, such as authorization_pending or
// invalid_grant. A code this library has never seen is kept as sent.
ErrorCode string
// ErrorDescription is the server's explanation, or empty when it sent none.
ErrorDescription string
// StatusCode is the HTTP status, or 0 when the refusal was reached locally:
// PollDeviceToken running past the code's lifetime.
StatusCode int
}
OauthError is the authorization server refusing a request: a 4xx whose body names an OAuth error code. It is never worth retrying as it stands.
errors.As to *Error also works, through Unwrap, with a Kind that follows the status; a 401 here means an unregistered client ID, never the API key.
func (*OauthError) Error ¶ added in v2.3.0
func (e *OauthError) Error() string
func (*OauthError) Is ¶ added in v2.3.0
func (e *OauthError) Is(target error) bool
Is answers errors.Is for ErrOauthAccessDenied and ErrOauthExpiredToken.
func (*OauthError) Unwrap ¶ added in v2.3.0
func (e *OauthError) Unwrap() error
Unwrap is the same refusal as an *Error, whose Kind follows the status and is bad_request when the refusal was local.
type OauthMetadata ¶ added in v2.3.0
type OauthMetadata struct {
Issuer string `json:"issuer"`
AuthorizationEndpoint string `json:"authorization_endpoint"`
TokenEndpoint string `json:"token_endpoint"`
DeviceAuthorizationEndpoint *string `json:"device_authorization_endpoint,omitempty"`
RevocationEndpoint *string `json:"revocation_endpoint,omitempty"`
ScopesSupported *[]string `json:"scopes_supported,omitempty"`
ResponseTypesSupported *[]string `json:"response_types_supported,omitempty"`
GrantTypesSupported *[]string `json:"grant_types_supported,omitempty"`
CodeChallengeMethodsSupported *[]string `json:"code_challenge_methods_supported,omitempty"`
TokenEndpointAuthMethodsSupported *[]string `json:"token_endpoint_auth_methods_supported,omitempty"`
AuthorizationResponseIssParameterSupported *bool `json:"authorization_response_iss_parameter_supported,omitempty"`
ClientIDMetadataDocumentSupported *bool `json:"client_id_metadata_document_supported,omitempty"`
RegistrationEndpoint *string `json:"registration_endpoint,omitempty"`
ServiceDocumentation *string `json:"service_documentation,omitempty"`
}
OauthMetadata is the authorization server's discovery document. An optional member the server did not send is nil.
type Option ¶
type Option func(*config) error
Option configures a Client.
func WithAPIKey ¶
WithAPIKey authenticates as the key's organization. Which fields a lookup answers with, and how many lookups are allowed, follow the key's plan; which databases are listed, and which of them may be downloaded, follow its licenses.
The database calls need a key carrying the db.download scope. Keys are default-deny, so an existing key does not reach them until the scope is added to it.
The key is trimmed, and blanks alone are no key. A control character left in it is refused, by New.
func WithBaseURL ¶
WithBaseURL points the client at a different deployment of the API.
Client.Oauth signs in at the apex rather than the API's host, since that is whose issuer it is: api. is dropped from the host and api-<env>. becomes <env>.; any other base URL is used as given.
func WithCache ¶ added in v2.10.0
WithCache sizes the per-client answer cache. Defaults are 10000 addresses and a one hour TTL.
func WithConcurrency ¶ added in v2.10.0
WithConcurrency sets how many batch requests - chunks of up to 1000 addresses - a batch keeps in flight. Default 8.
func WithHTTPClient ¶
WithHTTPClient supplies the HTTP client to send with, for a custom transport, proxy or timeout. Without it the SDK uses a client with a 30 second timeout.
The client is copied rather than mutated, and the copy adds a CheckRedirect that defers to yours (see DatabaseAPI.DownloadURL). A database transfer runs on a second copy with Timeout cleared, and is bounded by its context instead.
Every request reaches your transport already carrying User-Agent internetdata-go/<version>, so a program built on the SDK can put its own name first there.
func WithRetries ¶
WithRetries sets how many further attempts a transient failure gets. Default 2.
func WithoutCache ¶ added in v2.10.0
func WithoutCache() Option
WithoutCache turns caching off, so every lookup of a non-bogon address is served.
type Pkce ¶ added in v2.5.0
type Pkce struct {
// Verifier is 32 random bytes as 43 characters of unpadded base64url.
Verifier string
// Challenge is the verifier's SHA-256, as unpadded base64url.
Challenge string
// Method is always S256, the only method the server accepts.
Method string
}
Pkce is one sign-in's PKCE pair: Challenge goes in the authorization URL, Verifier to ExchangeAuthorizationCode.
type ProxyDetail ¶ added in v2.10.0
type ProxyDetail = api.ProxyDetail
The wire shapes a lookup answers with, re-exported so a consumer never has to name an internal package.
type PubproxyDetail ¶ added in v2.10.0
type PubproxyDetail = api.PubproxyDetail
The wire shapes a lookup answers with, re-exported so a consumer never has to name an internal package.
type RegisterOptions ¶ added in v2.8.0
type RegisterOptions struct {
// ClientName is shown to the person as the client's own claim, marked
// unverified, beside where its redirect goes.
ClientName string
}
RegisterOptions is what a registration asks for beyond its redirect URIs. An empty field is left out of the request rather than sent empty.
type Result ¶ added in v2.10.0
type Result struct {
// The answer as it was served, with the wire's own optionality intact. Its
// fields are promoted, so r.IsTor and r.Location read straight off the
// Result.
LookupResponse
}
Result is what a lookup answers.
A pointer member is one your plan does not include. It never means "we could not check", so nil and false are genuinely different answers: nil is "not in your plan", false is "checked, and no". BoolValue collapses the two for callers who only want to know whether an address is flagged. The same holds inside a shared object, so Location.City is nil on Unlimited.
A detail object that is present but empty means the flag above it is false. A populated one always carries every one of its keys, empty values included. IsBogon is true for a private or reserved address, which the client answers itself.
type Rwhois ¶ added in v2.10.0
The wire shapes a lookup answers with, re-exported so a consumer never has to name an internal package.
type SMTPDetail ¶ added in v2.10.0
type SMTPDetail = api.SMTPDetail
The wire shapes a lookup answers with, re-exported so a consumer never has to name an internal package.
type SSHDetail ¶ added in v2.10.0
The wire shapes a lookup answers with, re-exported so a consumer never has to name an internal package.
type SatelliteDetail ¶ added in v2.10.0
type SatelliteDetail = api.SatelliteDetail
The wire shapes a lookup answers with, re-exported so a consumer never has to name an internal package.
type TokenResponse ¶ added in v2.3.0
type TokenResponse struct {
AccessToken string `json:"access_token"`
TokenType string `json:"token_type"`
ExpiresIn int `json:"expires_in"`
RefreshToken *string `json:"refresh_token,omitempty"`
Scope *string `json:"scope,omitempty"`
ApikeyID *string `json:"mslm:apikey_id,omitempty"`
Apikey *string `json:"mslm:apikey,omitempty"`
}
TokenResponse is what a completed sign-in or a refresh hands back.
ApikeyID is set when the person picked one of their API keys and may still reveal it. Apikey, the key itself, additionally needs a sign-in rather than a refresh and a key whose secret can be read back, so ApikeyID without Apikey is normal. An empty Scope is present, not nil.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
api
Package api provides primitives to interact with the openapi HTTP API.
|
Package api provides primitives to interact with the openapi HTTP API. |
|
Package middleware holds the framework-agnostic half of a web middleware: resolve a client address, classify it, and decide whether to block.
|
Package middleware holds the framework-agnostic half of a web middleware: resolve a client address, classify it, and decide whether to block. |