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

                                                              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.