bootstrap

package
v0.9.3 Latest Latest
Warning

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

 Go to latest Published: Dec 19, 2022 License: MIT Imports: 17 Imported by: 0

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

func AddDNSRegistryFallback added in v0.9.3 

func AddDNSRegistryFallback(mlookup string, murls []string)

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.

Source Files

View all Source files

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
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.