rdap: github.com/openrdap/rdap/bootstrap Index | Files | Directories

package bootstrap

import "github.com/openrdap/rdap/bootstrap"

Package bootstrap implements an RDAP bootstrap client.

All RDAP queries are handled by an RDAP server. To help clients discover RDAP servers, IANA publishes Service Registry files (https://data.iana.org/rdap) for several query types: Domain names, IP addresses, and Autonomous Systems.

Given an RDAP query, this package finds the list of RDAP server URLs which can answer it. This includes downloading & parsing the Service Registry files.

Basic usage:

question := &bootstrap.Question{
  RegistryType: bootstrap.DNS,
  Query: "example.cz",
}

b := &bootstrap.Client{}

var answer *bootstrap.Answer
answer, err := b.Lookup(question)

if err == nil {
  for _, url := range answer.URLs {
    fmt.Println(url)
  }
}

Download and list the contents of the DNS Service Registry:

b := &bootstrap.Client{}

// Before you can use a Registry, you need to download it first.
err := b.Download(bootstrap.DNS) // Downloads https://data.iana.org/rdap/dns.json.

if err == nil {
  var dns *DNSRegistry = b.DNS()

  // Print TLDs with RDAP service.
  for tld, _ := range dns.File().Entries {
    fmt.Println(tld)
  }
}

You can configure bootstrap.Client{} with a custom http.Client, base URL (default https://data.iana.org/rdap), and custom cache. bootstrap.Question{} support Contexts (for timeout, etc.).

A bootstrap.Client caches the Service Registry files in memory for both performance, and courtesy to data.iana.org. The functions which make network requests are:

- Download()            - force download one of Service Registry file.
- DownloadWithContext() - force download one of Service Registry file.
- Lookup()              - download one Service Registry file if missing, or if the cached file is over (by default) 24 hours old.

Lookup() is intended for repeated usage: A long lived bootstrap.Client will download each of {asn,dns,ipv4,ipv6}.json once per 24 hours only, regardless of the number of calls made to Lookup(). You can still refresh them manually using Download() if required.

By default, Service Registry files are cached in memory. bootstrap.Client also supports caching the Service Registry files on disk. The default cache location is $HOME/.openrdap/.

Disk cache usage:

b := bootstrap.NewClient()
b.Cache = cache.NewDiskCache()

dsr := b.DNS()  // Tries to load dns.json from disk cache, doesn't exist yet, so returns nil.
b.Download(bootstrap.DNS) // Downloads dns.json, saves to disk cache.

b2 := bootstrap.NewClient()
b2.Cache = cache.NewDiskCache()

dsr2 := b.DNS()  // Loads dns.json from disk cache.

This package also implements the experimental Service Provider registry. Due to the experimental nature, no Service Registry file exists on data.iana.org yet, additionally the filename isn't known. The current filename used is serviceprovider-draft-03.json.

RDAP bootstrapping is defined in https://tools.ietf.org/html/rfc7484.

Index

Package Files

answer.go asn_registry.go client.go dns_registry.go file.go net_registry.go question.go service_provider_registry.go

Constants

const (
    // Default URL of the Service Registry files.
    DefaultBaseURL = "https://data.iana.org/rdap/"

    // Default cache timeout of Service Registries.
    DefaultCacheTimeout = time.Hour * 24
)

type ASNRegistry Uses

type ASNRegistry struct {
    // contains filtered or unexported fields
}

func NewASNRegistry Uses

func NewASNRegistry(json []byte) (*ASNRegistry, error)

NewASNRegistry creates an ASNRegistry from an ASN registry JSON document.

The document format is specified in https://tools.ietf.org/html/rfc7484#section-5.3.

func (*ASNRegistry) File Uses

func (a *ASNRegistry) File() *File

File returns a struct describing the registry's JSON document.

func (*ASNRegistry) Lookup Uses

func (a *ASNRegistry) Lookup(question *Question) (*Answer, error)

Lookup returns the RDAP base URLs for the AS number question |question|.

Example queries are: "AS1234", "as1234", and "1234".

type Answer Uses

type Answer struct {
    // Query looked up in the registry.
    //
    // This includes any canonicalisation performed to match the Service
    // Registry's data format. e.g. lowercasing of domain names, and removal of
    // "AS" from AS numbers.
    Query string

    // Matching service entry. Empty string if no match.
    Entry string

    // List of RDAP base URLs.
    URLs []*url.URL
}

Answer represents the result of bootstrapping a single query.

type Client Uses

type Client struct {
    HTTP    *http.Client        // HTTP client.
    BaseURL *url.URL            // Base URL of the Service Registry files. Default is DefaultBaseURL.
    Cache   cache.RegistryCache // Service Registry cache. Default is a MemoryCache.

    // Optional callback function for verbose messages.
    Verbose func(text string)
    // contains filtered or unexported fields
}

Client implements an RDAP bootstrap client.

func (*Client) ASN Uses

func (c *Client) ASN() *ASNRegistry

ASN returns the current ASN Registry (or nil if the registry file hasn't been Download()ed).

This function never initiates a network transfer.

func (*Client) DNS Uses

func (c *Client) DNS() *DNSRegistry

DNS returns the current DNS Registry (or nil if the registry file hasn't been Download()ed).

This function never initiates a network transfer.

func (*Client) Download Uses

func (c *Client) Download(registry RegistryType) error

Download downloads a single bootstrap registry file.

On success, the relevant Registry is refreshed. Use the matching accessor (ASN(), DNS(), IPv4(), or IPv6()) to access it.

func (*Client) DownloadWithContext Uses

func (c *Client) DownloadWithContext(ctx context.Context, registry RegistryType) error

DownloadWithContext downloads a single bootstrap registry file, with context |context|.

On success, the relevant Registry is refreshed. Use the matching accessor (ASN(), DNS(), IPv4(), or IPv6()) to access it.

func (*Client) IPv4 Uses

func (c *Client) IPv4() *NetRegistry

IPv4 returns the current IPv4 Registry (or nil if the registry file hasn't been Download()ed).

This function never initiates a network transfer.

func (*Client) IPv6 Uses

func (c *Client) IPv6() *NetRegistry

IPv6 returns the current IPv6 Registry (or nil if the registry file hasn't been Download()ed).

This function never initiates a network transfer.

func (*Client) Lookup Uses

func (c *Client) Lookup(question *Question) (*Answer, error)

Lookup returns the RDAP base URLs for the bootstrap question |question|.

func (*Client) ServiceProvider Uses

func (c *Client) ServiceProvider() *ServiceProviderRegistry

ServiceProvider returns the current ServiceProvider Registry (or nil if the registry file hasn't been Download()ed).

This function never initiates a network transfer.

type DNSRegistry Uses

type DNSRegistry struct {
    // contains filtered or unexported fields
}

func NewDNSRegistry Uses

func NewDNSRegistry(json []byte) (*DNSRegistry, error)

NewDNSRegistry creates a DNSRegistry from a DNS registry JSON document.

The document format is specified in https://tools.ietf.org/html/rfc7484#section-4.

func (*DNSRegistry) File Uses

func (d *DNSRegistry) File() *File

File returns a struct describing the registry's JSON document.

func (*DNSRegistry) Lookup Uses

func (d *DNSRegistry) Lookup(question *Question) (*Answer, error)

Lookup returns the RDAP base URLs for the domain name question |question|.

type File Uses

type File struct {
    // Fields from the JSON document.
    Description string
    Publication string
    Version     string

    // Map of service entries to RDAP base URLs.
    //
    // e.g. in ipv6.json, the following mapping:
    // "2c00::/12" => https://rdap.afrinic.net/rdap/,
    //                http://rdap.afrinic.net/rdap/.
    Entries map[string][]*url.URL

    // The file's JSON document.
    JSON []byte
}

File represents a bootstrap registry file (i.e. {asn,dns,ipv4,ipv6}.json).

func NewFile Uses

func NewFile(jsonDocument []byte) (*File, error)

NewFile constructs a File from a bootstrap registry file.

type NetRegistry Uses

type NetRegistry struct {
    // contains filtered or unexported fields
}

func NewNetRegistry Uses

func NewNetRegistry(json []byte, ipVersion int) (*NetRegistry, error)

NewNetRegistry creates a NetRegistry from an IPv4 or IPv6 registry JSON document. ipVersion must be 4 or 6.

The document formats are specified in https://tools.ietf.org/html/rfc7484#section-5.1 and https://tools.ietf.org/html/rfc7484#section-5.2.

func (*NetRegistry) File Uses

func (n *NetRegistry) File() *File

File returns a struct describing the registry's JSON document.

func (*NetRegistry) Lookup Uses

func (n *NetRegistry) Lookup(question *Question) (*Answer, error)

Lookup returns the RDAP base URLs for the IP address or CIDR range question |Question|.

Example queries are: "192.0.2.0", "192.0.2.0/25". "2001:db8::", "2001::db8::/62".

type Question Uses

type Question struct {
    // Bootstrap registry to query.
    RegistryType

    // Query text.
    Query string
    // contains filtered or unexported fields
}

Question represents a bootstrap query.

question := &bootstrap.Question{
  RegistryType: bootstrap.DNS,
  Query: "example.cz",
}

func (*Question) Context Uses

func (q *Question) Context() context.Context

Context returns the Question's context.

The returned context is always non-nil; it defaults to the background context.

func (*Question) WithContext Uses

func (q *Question) WithContext(ctx context.Context) *Question

WithContext returns a copy of the Question, with context |ctx|.

type Registry Uses

type Registry interface {
    Lookup(question *Question) (*Answer, error)
    File() *File
}

A Registry implements bootstrap lookups.

type RegistryType Uses

type RegistryType int

A RegistryType represents a bootstrap registry type.

const (
    DNS RegistryType = iota
    IPv4
    IPv6
    ASN
    ServiceProvider
)

func (RegistryType) Filename Uses

func (r RegistryType) Filename() string

Filename returns the JSON document filename: One of {asn,dns,ipv4,ipv6,service_provider}.json.

func (RegistryType) String Uses

func (r RegistryType) String() string

type ServiceProviderRegistry Uses

type ServiceProviderRegistry struct {
    // contains filtered or unexported fields
}

func NewServiceProviderRegistry Uses

func NewServiceProviderRegistry(json []byte) (*ServiceProviderRegistry, error)

NewServiceProviderRegistry creates a ServiceProviderRegistry from a Service Provider JSON document.

The document format is specified in https://datatracker.ietf.org/doc/draft-hollenbeck-regext-rdap-object-tag/.

func (*ServiceProviderRegistry) File Uses

func (s *ServiceProviderRegistry) File() *File

File returns a struct describing the registry's JSON document.

func (*ServiceProviderRegistry) Lookup Uses

func (s *ServiceProviderRegistry) Lookup(question *Question) (*Answer, error)

Lookup returns a list of RDAP base URLs for the entity question |question|.

e.g. for the handle "53774930-VRSN", the RDAP base URLs for "VRSN" are returned.

Missing/malformed/unknown service tags are not treated as errors. An empty list of URLs is returned in these cases.

Deprecated: Previously service tags used a TILDE char (e.g. ~VRSN) instead, these are still supported.

Directories

PathSynopsis
cachePackage cache implements RDAP Service Registry file caching.

Package bootstrap imports 16 packages (graph) and is imported by 1 packages. Updated 2018-06-05. Refresh now. Tools for package owners.