internetdata

package module
v2.13.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 26 Imported by: 1

README

InternetData InternetData Go Client Library

Go Reference license

The official Go client library for the InternetData API.

It tells you what InternetData's databases say about an IP address, an AS or a domain, and downloads the databases your organization is licensed for, in CSV.GZ or MMDB.

Getting Started

go get github.com/internetdata/sdk-go/v2

Requires Go 1.26 or newer. The module path ends in sdk-go, but the package it declares is internetdata:

import internetdata "github.com/internetdata/sdk-go/v2"

Usage

No API key needed to start. Unlimited, the free plan, answers where an address is, the AS and company behind it, its abuse contact, and whether it's a Tor exit, a relay, anycast, a carrier or satellite network, or runs SSH, SMTP, a web server, a DNS resolver or BitTorrent, limited per address per minute.

client, err := internetdata.New()
if err != nil {
    log.Fatal(err)
}

result, err := client.Lookup(ctx, "146.70.116.130")
if err != nil {
    log.Fatal(err)
}
fmt.Println(result.Location.Country)   // AT
fmt.Println(result.Asn.Name)           // M247 Europe SRL
fmt.Println(result.IsTor)              // false
With an API key

A paid plan answers every field: is_vpn, is_hosting, is_cdn and the four proxy flags as well, the provider and confidence behind each flag, the location down to the city, and the whois record. A free account tries every field, 100 lookups a day. Create a key in the console, then pass it in:

client, err := internetdata.New(internetdata.WithAPIKey(os.Getenv("INTERNETDATA_API_KEY")))

result, err := client.Lookup(ctx, "146.70.116.130")
fmt.Println(internetdata.BoolValue(result.IsVpn))   // true, on a paid plan

if vpn := result.Vpn; vpn != nil {
    fmt.Println(vpn.ProviderName)       // Mullvad, on a paid plan
}
An AS or a domain
asn, err := client.LookupASN(ctx, 9009)
fmt.Println(asn.Name, asn.Country)     // M247 Europe SRL RO

domain, err := client.LookupDomain(ctx, "example.com")
fmt.Println(domain.IsRegistered)       // true

Every plan answers an AS's registration and whether a domain is registered and which record types it has. A paid plan adds the AS's whois record, its prefixes, its rank, Tier 1 flag, upstreams, peers and downstreams, and the domains it hosts, and the domain's records, IP ranges and is_disposable. Neither is cached or batched, and Lookup takes an address alone: it refuses anything else as a bad_request before sending it.

Your own address
result, err := client.MyIP(ctx)
fmt.Println(result.IP)   // the address we saw this call come from

Same answer Lookup would give for that address, and the same cost against your allowance. It's deliberately not cached: which address you are is the whole question, and a machine that moves between networks would otherwise be told where it used to be.

Your plan and usage
acct, err := client.MyEntitlement(ctx)
fmt.Println(acct.Plan.Key)         // max
fmt.Println(acct.Plan.Name)        // Max, the name to show
fmt.Println(acct.Usage.Requests)   // 580
fmt.Println(acct.Usage.WindowEnd)  // when the allowance resets

Usage is counted against the anniversary of your subscription on a paid plan, not the calendar month and not the billing period, and against the UTC day on the free plan; it's the same number a lookup is gated on. HardLimit is nil on an uncapped plan, which is not the same as zero.

Batch lookup

Look up many addresses at once. Bogons and cached answers are handled locally, and everything else goes to the batch endpoint in chunks of up to 1000 addresses, in parallel. The batch endpoint needs a paid plan:

results, err := client.LookupBatch(ctx, []string{"146.70.116.130", "8.8.8.8", "1.1.1.1"})

for ip, result := range results {
    if result.Err != nil {
        fmt.Printf("%s: %v\n", ip, result.Err)
        continue
    }
    fmt.Printf("%s: %s\n", ip, result.Result.Location.Country)
}

Results are keyed by address, so duplicates in your list collapse into a single entry and one address failing never loses the rest: it carries its error as its value, with the status the API would have given that address on its own.

Pass as many addresses as you like; splitting them into chunks is the library's job. How many chunks are in flight at once, how many times a failed chunk is retried, and how long each attempt may take are configurable per call:

results, err := client.LookupBatch(ctx, manyIPs,
    internetdata.Concurrency(4), internetdata.Retries(4), internetdata.Timeout(10*time.Second))

Retries and Timeout work on Lookup, LookupASN, LookupDomain, MyIP and MyEntitlement too. The timeout bounds each attempt rather than the whole call, and defaults to the HTTP client's: 30 seconds unless WithHTTPClient supplied another.

Every request names the SDK in its User-Agent, internetdata-go/<version>, object storage's included. A program built on the SDK can put its own name first in the transport it passes to WithHTTPClient, which sees that header already set.

Caching

Address lookups are cached by default, so repeat lookups of the same address are free:

client, err := internetdata.New()

result, err := client.Lookup(ctx, "146.70.116.130")
fmt.Println(result.Asn.Asn)    // 9009, API request

result2, err := client.Lookup(ctx, "146.70.116.130")
fmt.Println(result2.Asn.Asn)   // 9009, no API request, result was cached

You can change the default cache variables (max size, TTL, etc) on initialization, or even disable it:

client, err := internetdata.New(internetdata.WithCache(50_000, 6*time.Hour))
clientNoCache, err := internetdata.New(internetdata.WithoutCache())
Private and reserved addresses

Private, loopback, link-local, documentation and multicast addresses (and their IPv6 equivalents, including the 6to4 and Teredo ranges) are answered locally, every flag false and every field empty, so they cost no request and no quota:

result, err := client.Lookup(ctx, "192.168.1.1")
result.IsBogon   // true, this answer was computed rather than served
result.IsTor     // false

Because the answer is computed rather than served, it always carries every field, whatever plan you are on. Do not read your plan's shape off a private address.

The check is available on the client, which is handy when your inputs are addresses anyway:

client.IsBogon("10.0.0.1")   // true
client.IsBogon("8.8.8.8")    // false

It is also callable on its own, if you want it without a client:

internetdata.IsBogon("10.0.0.1")   // true
Errors

Failures return an *internetdata.Error carrying a Kind, the API's own message, and a Retryable flag:

result, err := client.Lookup(ctx, "146.70.116.130")
var apiErr *internetdata.Error
if errors.As(err, &apiErr) {
    fmt.Println(apiErr.Kind, apiErr.Message, apiErr.Retryable())
}

Kind is one of bad_request, unauthorized, forbidden, rate_limited, quota_exceeded, server_error or network. A lookup's Message is the API's explanation. A database call's is its rc, which is what separates two refusals that share a status: NOT_LICENSED means buy it, LICENSE_EXPIRED means renew it, and IP_NOT_ALLOWED means the call came from an address the key or its organization does not allow, and all three are 403.

Note that rate_limited and quota_exceeded both arrive as HTTP 429 and are not the same thing. A rate limit carries Retry-After, and retrying later works; a spent quota needs your allowance raised or the window to roll over. The library retries rate limits for you, but not if your quota is exceeded.

Databases

The databases your organization is licensed for are under client.Database, for a key carrying the db.download scope. Every database published today is licensed:

client, err := internetdata.New(internetdata.WithAPIKey(os.Getenv("INTERNETDATA_API_KEY")))

databases, err := client.Database.List(ctx)
for _, db := range databases {
    fmt.Println(db.Base, db.Standing)   // bogon_ip licensed
}

Every database call hangs off client.Database, which is where the sibling VPNDetection library keeps the same seven calls.

The catalog

List returns one entry per database FAMILY, with your license beside it. A license covers the family, while a download names one of its versions, so the IDs you pass to everything else come from Versions:

for _, db := range databases {
    if db.Standing != internetdata.StandingLicensed {
        continue
    }
    for _, v := range db.Versions {
        fmt.Println(v.ID, v.Formats)    // vpn_ip_v1 [csvgz mmdb]
    }
}

Standing is licensed, expired or unlicensed, and LicenseType is what your license permits: evaluation, standard, redistribute, or nil when there is no license at all. Old versions are frozen rather than migrated, so both stay downloadable.

What is inside one, before you fetch it

Metadata carries the row count, the build date, the columns of each format and the byte size of each file, without downloading anything. Poll it to decide whether today's build is worth fetching, and read Size to budget a transfer before you start one:

meta, err := client.Database.Metadata(ctx, "vpn_ip_v1")
fmt.Println(meta.Updated, meta.Entries, meta.Size["mmdb"])

for _, column := range meta.Schema["csvgz"] {
    fmt.Println(column.Name, column.Type)
}
Downloading

DownloadFile writes one file to a path, streaming it straight to disk so that nothing bigger than a chunk is ever held in memory:

written, err := client.Database.DownloadFile(ctx, "vpn_ip_v1", internetdata.FormatMMDB, "./vpn_ip_v1.mmdb")
fmt.Printf("%d bytes\n", 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.

Or stream it into a writer of your own, or take a small one as bytes:

written, err := client.Database.Download(ctx, "vpn_ip_v1", internetdata.FormatMMDB, w)
raw, err := client.Database.DownloadBytes(ctx, "bogon_ip_v1", internetdata.FormatCSVGZ)

DownloadBytes holds the whole file in memory, and the catalog spans five orders of magnitude, so use DownloadFile for anything you have not measured against Metadata's Size.

Format is a defined string type, so Format("zip") compiles. Anything the API does not publish is refused before the request leaves, as a bad_request naming what is allowed; Valid is the same check for a format you take from a flag or a config file:

if !internetdata.Format(fromFlag).Valid() {
    // csvgz or mmdb
}
Downloading a named build

Each download call fetches the build that is live unless you name one. A database.updated webhook names the build it announces and carries its sha256, so a receiver that downloads after the next publish asks for that build to get the file the hash is of. client.Database.AtBuild(build) has the same four download calls, for that build:

written, err := client.Database.AtBuild(event.Data.Build).DownloadFile(ctx,
    "vpn_ip_v1", internetdata.FormatMMDB, "./vpn_ip_v1.mmdb")

A build is kept 7 days. Past that the call fails as bad_request with the message BUILD_GONE, and client.Database's own download calls fetch the live one.

Downloading it yourself

The API answers a download with a redirect to a time-limited URL on object storage. DownloadURL hands you that URL rather than following it, so you can pass it to a downloader, a job queue or another machine:

url, err := client.Database.DownloadURL(ctx, "vpn_ip_v1", internetdata.FormatMMDB)

The link is presigned and so authorizes itself; it carries no API key of yours, and the library never sends your key to object storage. The link only has to be valid when a transfer starts, so one already running isn't cut off when it lapses.

Verifying a download

Checksums returns all four digests the exporter publishes for one file:

sums, err := client.Database.Checksums(ctx, "vpn_ip_v1", internetdata.FormatMMDB)
fmt.Println(sums.SHA256)
Download history

Downloads is your organization's recent attempts, newest first, refusals included: a denial is what answers "it stopped working", and its absence answers nothing.

history, err := client.Database.Downloads(ctx, 50)
for _, attempt := range history {
    fmt.Println(attempt.Created, attempt.DatasetID, attempt.Outcome)
}
Sign in with OAuth (device flow)

A program running on the person's own machine can let them sign in with a browser and pick one of their API keys, instead of asking them to paste it:

client, err := internetdata.New()
device, err := client.Oauth.DeviceAuthorization(ctx, "your-client-id",
    internetdata.DeviceAuthorizationOptions{Scope: "account.read apikeys.read apikeys.reveal"})
fmt.Printf("Open %s and enter %s\n", device.VerificationURI, device.UserCode)

token, err := client.Oauth.PollDeviceToken(ctx, "your-client-id", device)
if token.Apikey == nil {
    log.Fatal("no API key came back: none was picked, or it cannot be revealed")
}
keyed, err := internetdata.New(internetdata.WithAPIKey(*token.Apikey))

A denied sign-in satisfies errors.Is(err, internetdata.ErrOauthAccessDenied) and a code that ran out errors.Is(err, internetdata.ErrOauthExpiredToken), and client IDs are issued on request from support@internetdata.io. client.Oauth.Revoke(ctx, "your-client-id", *token.RefreshToken) signs the machine out again.

Sign in with OAuth (authorization code)

An app that can take a browser redirect signs the person in there instead, with a PKCE pair made for that one sign-in:

client, err := internetdata.New()
redirectURI := "http://127.0.0.1:8765/callback"
pkce := client.Oauth.CreatePkce()

authURL, err := client.Oauth.AuthorizationURL("your-client-id", redirectURI, pkce.Challenge,
    internetdata.AuthorizationURLOptions{Scope: "apikeys.use", State: "your-state"})
// Open authURL in the browser. Its redirect to redirectURI carries code and state.
token, err := client.Oauth.ExchangeAuthorizationCode(ctx, "your-client-id", code, pkce.Verifier, redirectURI)

Check that state came back as you sent it before you exchange code, which works once. The client ID can also be the https URL of a client metadata document your app serves, and such an app is never handed a key, so token.Apikey stays nil.

Register a client

An app with no client ID, and no client metadata document to use as one, registers itself, then signs in with the ClientID it gets back as the client ID for AuthorizationURL and ExchangeAuthorizationCode:

client, err := internetdata.New()
registration, err := client.Oauth.Register(ctx, []string{"http://127.0.0.1:8765/callback"},
    internetdata.RegisterOptions{ClientName: "Your App"})

Each redirect URI must be https on a public host name, or http on a loopback address, which then matches any port. Nothing is kept until a person approves the client, so an app with no client ID saved can simply register again.

Absent is not false

Beyond the members every plan answers, each field is a pointer, because your key decides which of them the API sends, and so is each paid field inside a shared object, such as Location.City or Abuse.Phone. Unlimited leaves out IsVpn, IsHosting, IsCdn and the four proxy flags, the detail behind each flag but Tor's and relay's, and the whois record; a free-plan key's answer carries TrialExpired, true once its daily trial is spent. A nil pointer means "not in your plan", not "checked, and no".

internetdata.BoolValue(result.IsVpn)        // when you only want the flag
result.IsVpn == nil                         // on Unlimited: not in your plan
internetdata.BoolValue(result.TrialExpired) // a free-plan key's daily trial is spent

Other Libraries

There are official InternetData client libraries available for many languages including PHP, Python, Go, Java, and Ruby. See our GitHub at https://github.com/internetdata for more.

About InternetData

Geolocation, anonymity, ownership and network databases for IP addresses and AS numbers, licensed as files you download and query yourself.

InternetData

License

This project is licensed under the MIT License.

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

View Source
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.

View Source
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.

View Source
const (
	DownloadOutcomeOK           = api.DownloadOutcomeOk
	DownloadOutcomeUnauthorized = api.DownloadOutcomeUnauthorized
	DownloadOutcomeDenied       = api.DownloadOutcomeDenied
	DownloadOutcomeExpired      = api.DownloadOutcomeExpired
	DownloadOutcomeUnknown      = api.DownloadOutcomeUnknown
	DownloadOutcomeUnavailable  = api.DownloadOutcomeUnavailable
)
View Source
const DefaultBaseURL = "https://api.internetdata.io"

DefaultBaseURL is the production API. Override it with WithBaseURL.

Variables

View Source
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

func BoolValue(v *bool) bool

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

func IsBogon(ip string) bool

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

type Asn = api.Asn

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

type AsnPrefix = api.AsnPrefix

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

type BatchResult struct {
	Result *Result
	Err    error
}

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

func (b *BuildDownloads) DownloadURL(ctx context.Context, id string, format Format) (string, error)

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 New

func New(opts ...Option) (*Client, error)

New builds a client. With no options it queries the production API without a key.

func (*Client) IsBogon added in v2.10.0

func (c *Client) IsBogon(ip string) bool

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

func (c *Client) Lookup(ctx context.Context, ip string, opts ...LookupOption) (*Result, error)

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

func (c *Client) MyIP(ctx context.Context, opts ...LookupOption) (*Result, error)

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

type Company = api.Company

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

type Database = api.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

func (d *DatabaseAPI) Checksums(ctx context.Context, id string, format Format) (*Checksums, error)

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

func (d *DatabaseAPI) DownloadBytes(ctx context.Context, id string, format Format) ([]byte, error)

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

func (d *DatabaseAPI) DownloadURL(ctx context.Context, id string, format Format) (string, error)

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 Date

type Date = types.Date

Date is a calendar date with no time of day, as DatabaseMetadata.Updated carries.

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

type DomainDNS = api.DomainDNS

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

type DownloadAttempt = api.Download

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.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Retryable

func (e *Error) Retryable() bool

Retryable reports whether retrying this exact request could succeed.

func (*Error) Unwrap

func (e *Error) Unwrap() error

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.

const (
	KindBadRequest    ErrorKind = "bad_request"
	KindUnauthorized  ErrorKind = "unauthorized"
	KindForbidden     ErrorKind = "forbidden"
	KindRateLimited   ErrorKind = "rate_limited"
	KindQuotaExceeded ErrorKind = "quota_exceeded"
	KindServerError   ErrorKind = "server_error"
	KindNetwork       ErrorKind = "network"
)

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.

const (
	FormatCSVGZ Format = "csvgz"
	FormatMMDB  Format = "mmdb"
)

func (Format) Valid added in v2.1.0

func (f Format) Valid() bool

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

type Location = api.Location

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

func (o *OauthAPI) CreatePkce() Pkce

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

func (o *OauthAPI) PkceChallenge(verifier string) string

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.

func (*OauthAPI) Revoke added in v2.3.0

func (o *OauthAPI) Revoke(ctx context.Context, clientID, token string) error

Revoke ends a token. A refresh token ends the whole sign-in and every token it issued, which is how a program signs the machine out; an access token ends only itself. The server answers the same for any token, known or not.

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

func WithAPIKey(key string) Option

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

func WithBaseURL(rawURL string) Option

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

func WithCache(size int, ttl time.Duration) Option

WithCache sizes the per-client answer cache. Defaults are 10000 addresses and a one hour TTL.

func WithConcurrency added in v2.10.0

func WithConcurrency(n int) Option

WithConcurrency sets how many batch requests - chunks of up to 1000 addresses - a batch keeps in flight. Default 8.

func WithHTTPClient

func WithHTTPClient(client *http.Client) Option

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

func WithRetries(n int) Option

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

type Rwhois = api.Rwhois

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

type SSHDetail = api.SSHDetail

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 Standing

type Standing = api.Standing

Standing is where a license stands: live, lapsed, or never bought.

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.

type WebDetail added in v2.10.0

type WebDetail = api.WebDetail

The wire shapes a lookup answers with, re-exported so a consumer never has to name an internal package.

type Whois added in v2.10.0

type Whois = api.Whois

The wire shapes a lookup answers with, re-exported so a consumer never has to name an internal package.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址