bootstrap

package
Version: v0.9.0 Latest Latest
Warning

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

Go to latest
Published: Dec 2, 2018 License: MIT Imports: 16 Imported by: 4

Documentation

Overview

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

Constants

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

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

Variables

This section is empty.

Functions

This section is empty.

Types

type ASNRegistry

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

func NewASNRegistry

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

func (a *ASNRegistry) File() *File

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

func (*ASNRegistry) Lookup

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

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

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

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

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

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

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

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

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

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

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

func (*Client) ServiceProvider

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

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

func NewDNSRegistry

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

func (d *DNSRegistry) File() *File

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

func (*DNSRegistry) Lookup

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

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

type File

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

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

NewFile constructs a File from a bootstrap registry file.

type NetRegistry

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

func NewNetRegistry

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

func (n *NetRegistry) File() *File

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

func (*NetRegistry) Lookup

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

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

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

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

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

type Registry

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

A Registry implements bootstrap lookups.

type RegistryType

type RegistryType int

A RegistryType represents a bootstrap registry type.

const (
	DNS RegistryType = iota
	IPv4
	IPv6
	ASN
	ServiceProvider
)

func (RegistryType) Filename

func (r RegistryType) Filename() string

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

func (RegistryType) String

func (r RegistryType) String() string

type ServiceProviderRegistry

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

func NewServiceProviderRegistry

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

func (s *ServiceProviderRegistry) File() *File

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

func (*ServiceProviderRegistry) Lookup deprecated

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

Path Synopsis
Package cache implements RDAP Service Registry file caching.
Package cache implements RDAP Service Registry file caching.

Jump to

Keyboard shortcuts

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