czds

package module
v1.4.0 Latest Latest
Warning

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

 Go to latest Published: Apr 5, 2026 License: GPL-3.0 Imports: 14 Imported by: 0

README

CZDS

Go Report Card PkgGoDev docker

A utility and Go library implementing a client to the CZDS REST API, using both the documented and undocumented API endpoints.

CZDS API

The Go API allows you to perform almost any action available in the web interface. See the API documentation for details.

CZDS CLI

A unified command-line interface that provides all functionality through subcommands:

  • download (alias: dl) - Download zone files from czds.icann.org
  • request (alias: req) - Submit new zone requests or modify existing ones
  • status (alias: st) - View information about zone file requests
  • version - Print version information
Features
  • Can be used as a standalone client or embedded as a library in other applications
  • Automatically refreshes authorization token if expired during download
  • Can save downloaded zones as named by Content-Disposition or URL name
  • Can compare local and remote file size and modification time to skip redownloading unchanged zones
  • Can download multiple zones in parallel
  • Docker image available
Usage
czds - CZDS (Centralized Zone Data Service) client

Usage:
  czds <command> [options]

Available Commands:
  download, dl    Download zone files from CZDS
  request, req    Request access to zones, extensions, cancellations
  status, st      Check status of zone requests and generate reports
  version         Print version information
  help            Show this help message

Use "czds <command> -h" for more information about a command.

Global Options:
  -username string    Username to authenticate with (or set CZDS_USERNAME env var)
  -password string    Password to authenticate with (or set CZDS_PASSWORD env var)
  -verbose            Enable verbose logging

Examples:
  czds download -parallel 10 com org
  czds request -request-all -reason "Research project"
  czds status -zone com
Authentication

The czds command supports multiple authentication methods:

  1. Command-line flags: -username and -password
  2. Environment variables: CZDS_USERNAME and CZDS_PASSWORD

Environment variables are checked first and used as defaults if the corresponding flags are not provided.

Download Subcommand

Download zone files from CZDS in parallel.

Zones can be specified either using the -zones flag with a comma-separated list, or as positional arguments.

Download Usage
Usage: czds download [OPTIONS] [zones...]

Download zone files from CZDS

Options:
  -exclude string
     don't fetch these zones
  -force
     force redownloading the zone even if it already exists on local disk with same size and modification date
  -out string
     path to save downloaded zones to (default "zones")
  -parallel uint
     number of zones to download in parallel (default 5)
  -password string
     password to authenticate with (or set CZDS_PASSWORD env var)
  -progress
     show download progress for large files (>50MB)
  -quiet
     suppress progress printing
  -redownload
     redownload zones that are newer on the remote server than local copy
  -retries uint
     max retry attempts per zone file download (default 3)
  -urlname
     use the filename from the url link as the saved filename instead of the file header
  -username string
     username to authenticate with (or set CZDS_USERNAME env var)
  -verbose
     enable verbose logging
  -zones string
     comma separated list of zones to download, defaults to all
Download Examples
czds download                                # Download all available zones
czds download -zones com,org                 # Download specific zones
czds download -parallel 10 -out ./zones     # Download with 10 parallel workers
czds download -force -zones com              # Force redownload of com zone
czds download -exclude com,net               # Download all except com and net
czds download -progress -zones com           # Download with progress reporting

# Zones can also be specified as positional arguments:
czds download com org net                    # Download com, org, and net zones

# Using environment variables:
export CZDS_USERNAME="your_username"
export CZDS_PASSWORD="your_password"
czds download -verbose
Webhook Integration

The download command supports webhook integration for pre-download approval and post-download notifications via environment variables:

Environment Variables:

  • PRECHECK_WEBHOOK_URL - Batch pre-download approval endpoint (full URL)
  • NOTIFICATION_WEBHOOK_URL - Post-download notification endpoint (full URL)

Pre-Check: All zones are checked in a single batch request before downloads start. Zones with should_download: false are skipped.

Notifications: Sent immediately after each zone download completes (single-zone batches to maintain batch API format).

Failure Handling: If pre-check fails (network error, server error), all zones proceed anyway (fail-open).

Example:

export PRECHECK_WEBHOOK_URL=https://example.com/addzone/check
export NOTIFICATION_WEBHOOK_URL=https://example.com/addzone
czds download

See cmd/webhook/README.md for API details and server examples.

Request Subcommand

Submit a new zone request or modify an existing CZDS request. Be sure to view and accept the terms and conditions with the -terms flag.

Request Usage
Usage: czds request [OPTIONS]

Request access to zones, extensions, cancellations

Options:
  -cancel string
     comma separated list of zones to cancel outstanding requests for
  -exclude string
     comma separated list of zones to exclude from request-all or extend-all
  -extend string
     comma separated list of zones to request extensions
  -extend-all
     extend all possible zones
  -password string
     password to authenticate with (or set CZDS_PASSWORD env var)
  -reason string
     reason to request zone access
  -request string
     comma separated list of zones to request
  -request-all
     request all available zones
  -status
     print status of zones
  -terms
     print CZDS Terms & Conditions
  -username string
     username to authenticate with (or set CZDS_USERNAME env var)
  -verbose
     enable verbose logging
Request Examples
czds request -terms                              # Print terms and conditions
czds request -status                             # Show TLD status
czds request -request com,org -reason "Research" # Request specific TLDs
czds request -request-all -reason "Research"     # Request all available TLDs
czds request -extend com,org                     # Extend specific TLDs
czds request -extend-all                         # Extend all possible TLDs
czds request -cancel com,org                     # Cancel requests for TLDs

# View zones able to be requested:
czds request -status | grep -v pending | grep -v approved

Status Subcommand

View information about current zone file requests

Status Usage

By default the status subcommand prints high-level information about all CZDS requests, like the reports page on CZDS. Detailed information about a particular zone can be displayed with the -zone or -id flag.

Usage: czds status [OPTIONS]

Check status of zone requests and generate reports

Options:
  -id string
     ID of specific zone request to lookup, defaults to printing all
  -password string
     password to authenticate with (or set CZDS_PASSWORD env var)
  -progress
     show download progress for CSV reports
  -report string
     filename to save report CSV to, '-' for stdout
  -username string
     username to authenticate with (or set CZDS_USERNAME env var)
  -verbose
     enable verbose logging
  -zone string
     same as -id, but prints the request by zone name
Status Examples
czds status                          # List all requests
czds status -zone com                # Show details for com zone
czds status -id REQUEST_ID           # Show details for specific request
czds status -report report.csv       # Generate CSV report
czds status -report report.csv -progress # Generate CSV with progress

Show all requests:

$ czds status
TLD     ID      UnicodeTLD      Status  Created Updated Expires SFTP
xn--mxtq1m e59839f1-d69d-4970-9a15-7b49f3592065 政府 Approved Wed Jan 30 08:00:42 2019 Wed Jan 30 08:53:41 2019 Sat Jan 12 08:53:41 2030 false
aigo c6886423-b67d-43b6-828f-9d5a6cb3e6a3 aigo Pending Wed Jan 30 08:00:41 2019 Wed Jan 30 08:01:38 2019  false
barclaycard fa6d9c14-17ac-4b15-baf6-2d10g8e806fe barclaycard Pending Wed Jan 30 08:00:41 2019 Wed Jan 30 08:01:38 2019  false
fans 977d8589-9cec-41ef-b62e-0d3f0cf863e0 fans Pending Wed Jan 30 08:00:41 2019 Wed Jan 30 08:01:38 2019  false
live 8c95ccae-ae4d-4028-8997-655b132f542d live Approved Wed Jan 30 08:00:41 2019 Wed Jan 30 16:40:15 2019 Sat Jan 12 16:40:13 2030 false
onyourside 259aa66b-ac77-43db-a09a-9d3f57cf0e6b onyourside Pending Wed Jan 30 08:00:41 2019 Wed Jan 30 08:02:16 2019  false
wtc 67f5b31d-19f0-4071-a176-25ff71f509f7 wtc Pending Wed Jan 30 08:00:41 2019 Wed Jan 30 08:02:55 2019  false
xn--d1acj3b 69929632-ed92-437a-b140-fff4b0d771a7 дети Approved Wed Jan 30 08:00:41 2019 Wed Jan 30 10:55:03 2019 Tue Apr 30 10:55:03 2019 false

Lookup specific request details:

$ czds status -zone red
ID:     a056b38d-0080-4097-95cb-014b35ed4cb7
TLD:    red (red)
Status: approved
Created:        Wed Jan 30 08:00:41 2019
Updated:        Thu Jan 31 20:51:22 2019
Expires:        Sun Jan 13 20:51:20 2030
Request IP:     123.456.789.123
FTP IPs:         []
Reason: ...
History:
        Wed Jan 30 08:00:41 2019        Request submitted
        Wed Jan 30 08:02:16 2019        Request status change to Pending
        Thu Jan 31 20:51:22 2019        Request status change to Approved

Building

Just run make!

make

Docker

Using command-line flags:

docker run --rm -v /path/to/zones/:/zones ghcr.io/lanrat/czds download -out /zones -username "$USERNAME" -password "$PASSWORD"

Using environment variables:

docker run --rm -v /path/to/zones/:/zones -e CZDS_USERNAME="$USERNAME" -e CZDS_PASSWORD="$PASSWORD" ghcr.io/lanrat/czds -out /zones download

Documentation

Overview

Package czds implements a client to the CZDS REST API using both the documented and undocumented API endpoints.

The CZDS (Centralized Zone Data Service) allows authorized users to access DNS zone files for top-level domains (TLDs). This package provides a complete Go client for downloading zone files, managing access requests, and checking request status.

Basic Usage

Create a client and authenticate: 

client := czds.NewClient("username", "password")
ctx := context.Background()
err := client.AuthenticateWithContext(ctx)
if err != nil {
	log.Fatal(err)
}

Downloading Zone Files

Download all available zones: 

ctx := context.Background()
links, err := client.GetLinksWithContext(ctx)
if err != nil {
	log.Fatal(err)
}

for _, link := range links {
	err := client.DownloadZoneWithContext(ctx, link, "zones/")
	if err != nil {
		log.Printf("Failed to download %s: %v", link, err)
	}
}

Download a specific zone to a writer: 

ctx := context.Background()
var buf bytes.Buffer
bytesWritten, err := client.DownloadZoneToWriterWithContext(ctx, zoneURL, &buf)
if err != nil {
	log.Fatal(err)
}
fmt.Printf("Downloaded %d bytes\n", bytesWritten)

Managing Zone Requests

Request access to new zones: 

ctx := context.Background()
err := client.RequestTLDsWithContext(ctx, []string{"com", "org"}, "Research purposes")
if err != nil {
	log.Fatal(err)
}

Check request status: 

ctx := context.Background()
requests, err := client.GetAllRequestsWithContext(ctx, "")
if err != nil {
	log.Fatal(err)
}

for _, req := range requests {
	fmt.Printf("Zone: %s, Status: %s\n", req.TLD, req.Status)
}

Extend existing requests: 

ctx := context.Background()
err := client.ExtendTLDWithContext(ctx, "com")
if err != nil {
	log.Fatal(err)
}

Context Support

All operations support context for cancellation and timeouts: 

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

err := client.AuthenticateWithContext(ctx)
if err != nil {
	log.Fatal(err)
}

links, err := client.GetLinksWithContext(ctx)
if err != nil {
	log.Fatal(err)
}

Error Handling

The client automatically handles authentication token refresh during long-running operations. Network errors and API errors are returned as standard Go errors: 

if err := client.DownloadZoneWithContext(ctx, url, path); err != nil {
	if strings.Contains(err.Error(), "403") {
		log.Println("Access denied - check your permissions")
	} else if strings.Contains(err.Error(), "network") {
		log.Println("Network error - retrying...")
	} else {
		log.Printf("Unexpected error: %v", err)
	}
}

For more detailed examples and API documentation, see the individual function documentation.

Index

Constants

View Source 
const (
	// AuthURL is the production URL endpoint for authentication
	AuthURL = "https://account-api.icann.org/api/authenticate"
	// BaseURL is the production URL endpoint for the API
	BaseURL = "https://czds-api.icann.org"

	// TestAuthURL is the testing URL endpoint for authentication
	TestAuthURL = "https://account-api-test.icann.org/api/authenticate"
	// TestBaseURL is the testing URL endpoint for the API
	TestBaseURL = "https://czds-api-test.icann.org"
)
View Source 
const (
	RequestAll       = ""
	RequestSubmitted = "Submitted"
	RequestPending   = "Pending"
	RequestApproved  = "Approved"
	RequestDenied    = "Denied"
	RequestRevoked   = "Revoked"
	RequestExpired   = "Expired"
	RequestCanceled  = "Canceled"
)

Filters for RequestsFilter.Status Statuses for RequestStatus.Status

View Source 
const (
	SortAsc  = "asc"
	SortDesc = "desc"
)

Filters for RequestsSort.Direction

View Source 
const (
	SortByTLD         = "tld"
	SortByStatus      = "status"
	SortByLastUpdated = "last_updated"
	SortByExpiration  = "expired"
	SortByCreated     = "created"
	SortByAutoRenew   = "auto_renew"
)

Filters for RequestsSort.Field

View Source 
const (
	StatusAvailable = "available"
	StatusSubmitted = "submitted"
	StatusPending   = "pending"
	StatusApproved  = "approved"
	StatusDenied    = "denied"
	StatusExpired   = "expired"
	StatusCanceled  = "canceled"
	StatusRevoked   = "revoked"
)

Status from TLDStatus.CurrentStatus and RequestsInfo.Status

Variables

This section is empty.

Functions

This section is empty.

Types

type CancelRequestSubmission added in v1.0.6 

type CancelRequestSubmission struct {
	RequestID string `json:"integrationId"` // This is effectively 'requestId'
	TLDName   string `json:"tldName"`
}

CancelRequestSubmission contains request cancellation arguments passed to CancelRequest()

type Client 

type Client struct {
	HTTPClient *http.Client
	AuthURL    string
	BaseURL    string
	// UserAgent is the User-Agent header value sent with HTTP requests.
	// If empty, no User-Agent header will be set.
	UserAgent string

	Creds Credentials
	// contains filtered or unexported fields
}

Client stores all session information for czds authentication and manages token renewal

func NewClient 

func NewClient(username, password string) *Client

NewClient returns a new instance of the CZDS Client with the default production URLs

func (*Client) Authenticate deprecated 

func (c *Client) Authenticate() error

Authenticate tests the client's credentials and gets an authentication token from the server. Calling this is optional. All other functions will check the auth state on their own first and authenticate if necessary. This function uses a background context.

Deprecated: Use AuthenticateWithContext for context cancellation support.

func (*Client) AuthenticateWithContext added in v1.3.0 

func (c *Client) AuthenticateWithContext(ctx context.Context) error

AuthenticateWithContext authenticates the client with CZDS using the provided credentials. It obtains and stores an authentication token that will be used for subsequent API calls. The operation can be cancelled using the provided context.

func (*Client) CancelRequest deprecated added in v1.0.6 

func (c *Client) CancelRequest(cancel *CancelRequestSubmission) (*RequestsInfo, error)

CancelRequest cancels a pending zone access request. Only requests in pending status can be cancelled.

Deprecated: Use CancelRequestWithContext for context cancellation support.

func (*Client) CancelRequestWithContext added in v1.3.0 

func (c *Client) CancelRequestWithContext(ctx context.Context, cancel *CancelRequestSubmission) (*RequestsInfo, error)

CancelRequestWithContext cancels a pending zone access request. Only requests in pending status can be cancelled.

func (*Client) DownloadAllRequests deprecated 

func (c *Client) DownloadAllRequests(output io.Writer) error

DownloadAllRequests downloads a CSV report of all zone requests to the provided writer. This corresponds to the "Download All Requests" button on the CZDS portal.

Deprecated: Use DownloadAllRequestsWithContext for context cancellation support.

func (*Client) DownloadAllRequestsWithContext added in v1.3.0 

func (c *Client) DownloadAllRequestsWithContext(ctx context.Context, output io.Writer) error

DownloadAllRequestsWithContext downloads a CSV report of all zone requests to the provided writer. This corresponds to the "Download All Requests" button on the CZDS portal.

func (*Client) DownloadZone deprecated 

func (c *Client) DownloadZone(url, destinationPath string) error

DownloadZone downloads a zone file from the given URL and saves it to the specified file path. The URL should be retrieved from GetLinks(). If an error occurs, any partially downloaded file is removed.

Deprecated: Use DownloadZoneWithContext for context cancellation support.

func (*Client) DownloadZoneToWriter deprecated 

func (c *Client) DownloadZoneToWriter(url string, dest io.Writer) (int64, error)

DownloadZoneToWriter downloads a zone file from the given URL and writes it to the provided io.Writer. It returns the number of bytes written and any error encountered.

Deprecated: Use DownloadZoneToWriterWithContext for context cancellation support.

func (*Client) DownloadZoneToWriterWithContext added in v1.3.0 

func (c *Client) DownloadZoneToWriterWithContext(ctx context.Context, url string, dest io.Writer) (int64, error)

DownloadZoneToWriterWithContext downloads a zone file from the given URL and writes it to the provided io.Writer. It returns the number of bytes written and any error encountered. The download can be cancelled using the provided context.

func (*Client) DownloadZoneWithContext added in v1.3.0 

func (c *Client) DownloadZoneWithContext(ctx context.Context, url, destinationPath string) error

DownloadZoneWithContext downloads a zone file from the given URL and saves it to the specified file path. The operation can be cancelled using the provided context. If an error occurs, any partially downloaded file is removed.

func (*Client) ExtendAllTLDs deprecated added in v1.2.0 

func (c *Client) ExtendAllTLDs() ([]string, error)

ExtendAllTLDs is a helper function to request extensions for all extensible TLDs. It returns the list of TLDs for which extensions were requested.

Deprecated: Use ExtendAllTLDsWithContext for context cancellation support.

func (*Client) ExtendAllTLDsExcept deprecated added in v1.2.12 

func (c *Client) ExtendAllTLDsExcept(except []string) ([]string, error)

ExtendAllTLDsExcept requests extensions for all extensible TLDs, excluding any TLDs listed in the except parameter. It returns the list of TLDs for which extensions were requested.

Deprecated: Use ExtendAllTLDsExceptWithContext for context cancellation support.

func (*Client) ExtendAllTLDsExceptWithContext added in v1.3.0 

func (c *Client) ExtendAllTLDsExceptWithContext(ctx context.Context, except []string) ([]string, error)

ExtendAllTLDsExceptWithContext requests extensions for all extensible TLDs, excluding any TLDs listed in the except parameter. It returns the list of TLDs for which extensions were requested.

func (*Client) ExtendAllTLDsWithContext added in v1.3.0 

func (c *Client) ExtendAllTLDsWithContext(ctx context.Context) ([]string, error)

ExtendAllTLDsWithContext is a helper function to request extensions for all extensible TLDs. It returns the list of TLDs for which extensions were requested.

func (*Client) ExtendTLD deprecated added in v1.2.0 

func (c *Client) ExtendTLD(tld string) error

ExtendTLD is a helper function that requests an extension for the specified TLD. The TLD must have an approved request that is marked as extensible from GetRequestInfo().

Deprecated: Use ExtendTLDWithContext for context cancellation support.

func (*Client) ExtendTLDWithContext added in v1.3.0 

func (c *Client) ExtendTLDWithContext(ctx context.Context, tld string) error

ExtendTLDWithContext is a helper function that requests an extension for the specified TLD. The TLD must have an approved request that is marked as extensible.

func (*Client) GetAllRequests deprecated added in v1.2.0 

func (c *Client) GetAllRequests(status string) ([]Request, error)

GetAllRequests returns all zone requests with the specified status. Status should be one of the constant czds.Status* strings. Warning: for a large number of results, may be slow as it handles pagination automatically.

Deprecated: Use GetAllRequestsWithContext for context cancellation support.

func (*Client) GetAllRequestsWithContext added in v1.3.0 

func (c *Client) GetAllRequestsWithContext(ctx context.Context, status string) ([]Request, error)

GetAllRequestsWithContext retrieves all zone requests with the specified status. It handles pagination automatically to return the complete list of requests.

func (*Client) GetDownloadInfo deprecated 

func (c *Client) GetDownloadInfo(url string) (*DownloadInfo, error)

GetDownloadInfo retrieves metadata about a zone file download without downloading the file itself. It performs a HEAD request to get information like file size, last modified time, and filename.

Deprecated: Use GetDownloadInfoWithContext for context cancellation support.

func (*Client) GetDownloadInfoWithContext added in v1.3.0 

func (c *Client) GetDownloadInfoWithContext(ctx context.Context, url string) (*DownloadInfo, error)

GetDownloadInfoWithContext retrieves metadata about a zone file download without downloading the file itself. It performs a HEAD request to get information like file size, last modified time, and filename. The operation can be cancelled using the provided context. 

func (c *Client) GetLinks() ([]string, error)

GetLinks returns all zone download links available to the authenticated user. The returned URLs can be used with the download functions to retrieve zone files.

Deprecated: Use GetLinksWithContext for context cancellation support.

func (*Client) GetLinksWithContext added in v1.3.0 

func (c *Client) GetLinksWithContext(ctx context.Context) ([]string, error)

GetLinksWithContext retrieves all zone download links available to the authenticated user. It returns a slice of URLs that can be used with the download functions. The operation can be cancelled using the provided context.

func (*Client) GetRequestInfo deprecated 

func (c *Client) GetRequestInfo(requestID string) (*RequestsInfo, error)

GetRequestInfo gets detailed information about a particular request and its timeline. It retrieves comprehensive request details as seen on the CZDS dashboard page "https://czds.icann.org/zone-requests/{ID}".

Deprecated: Use GetRequestInfoWithContext for context cancellation support.

func (*Client) GetRequestInfoWithContext added in v1.3.0 

func (c *Client) GetRequestInfoWithContext(ctx context.Context, requestID string) (*RequestsInfo, error)

GetRequestInfoWithContext retrieves detailed information about a specific zone access request, including its status timeline and history. The operation can be cancelled using the provided context.

func (*Client) GetRequests deprecated 

func (c *Client) GetRequests(filter *RequestsFilter) (*RequestsResponse, error)

GetRequests retrieves zone access requests based on the provided filter criteria. It supports pagination and filtering by status, as seen on the CZDS dashboard page "https://czds.icann.org/zone-requests/all".

Deprecated: Use GetRequestsWithContext for context cancellation support.

func (*Client) GetRequestsWithContext added in v1.3.0 

func (c *Client) GetRequestsWithContext(ctx context.Context, filter *RequestsFilter) (*RequestsResponse, error)

GetRequestsWithContext retrieves zone access requests based on the provided filter criteria. It supports pagination and filtering by status. The operation can be cancelled using the provided context.

func (*Client) GetTLDStatus deprecated 

func (c *Client) GetTLDStatus() ([]TLDStatus, error)

GetTLDStatus gets the current status of all TLDs and their availability for requesting. It returns information about which TLDs can be requested for zone access.

Deprecated: Use GetTLDStatusWithContext for context cancellation support.

func (*Client) GetTLDStatusWithContext added in v1.3.0 

func (c *Client) GetTLDStatusWithContext(ctx context.Context) ([]TLDStatus, error)

GetTLDStatusWithContext retrieves the current status of all TLDs and their availability for requesting. It returns a slice of TLDStatus containing information about each TLD.

func (*Client) GetTerms deprecated 

func (c *Client) GetTerms() (*Terms, error)

GetTerms gets the current terms and conditions from the CZDS portal. The terms are retrieved from "https://czds.icann.org/terms-and-conditions" and are required to accept when submitting a new zone access request.

Deprecated: Use GetTermsWithContext for context cancellation support.

func (*Client) GetTermsWithContext added in v1.3.0 

func (c *Client) GetTermsWithContext(ctx context.Context) (*Terms, error)

GetTermsWithContext retrieves the current terms and conditions from the CZDS portal. This information is required when submitting new zone access requests.

func (*Client) GetZoneRequestID deprecated added in v1.2.0 

func (c *Client) GetZoneRequestID(zone string) (string, error)

GetZoneRequestID returns the most recent request ID for the given zone. It searches through paginated results to find the request for the specified zone name.

Deprecated: Use GetZoneRequestIDWithContext for context cancellation support.

func (*Client) GetZoneRequestIDWithContext added in v1.3.0 

func (c *Client) GetZoneRequestIDWithContext(ctx context.Context, zone string) (string, error)

GetZoneRequestIDWithContext retrieves the most recent request ID for the specified zone. It searches through paginated results to find the request for the given zone name.

func (*Client) RequestAllTLDs deprecated 

func (c *Client) RequestAllTLDs(reason string) ([]string, error)

RequestAllTLDs is a helper function to request access to all available TLDs with the provided reason. It returns the list of TLDs that were requested.

Deprecated: Use RequestAllTLDsWithContext for context cancellation support.

func (*Client) RequestAllTLDsExcept deprecated added in v1.2.12 

func (c *Client) RequestAllTLDsExcept(reason string, except []string) ([]string, error)

RequestAllTLDsExcept requests access to all available TLDs with the provided reason, excluding the TLDs listed in the except parameter. It returns the list of TLDs that were requested.

Deprecated: Use RequestAllTLDsExceptWithContext for context cancellation support.

func (*Client) RequestAllTLDsExceptWithContext added in v1.3.0 

func (c *Client) RequestAllTLDsExceptWithContext(ctx context.Context, reason string, except []string) ([]string, error)

RequestAllTLDsExceptWithContext requests access to all available TLDs with the provided reason, excluding the TLDs listed in the except parameter. It returns the list of TLDs that were requested.

func (*Client) RequestAllTLDsWithContext added in v1.3.0 

func (c *Client) RequestAllTLDsWithContext(ctx context.Context, reason string) ([]string, error)

RequestAllTLDsWithContext is a helper function to request access to all available TLDs with the provided reason. It returns the list of TLDs that were requested.

func (*Client) RequestExtension deprecated added in v1.2.0 

func (c *Client) RequestExtension(requestID string) (*RequestsInfo, error)

RequestExtension submits a request to extend access for a zone request. Extensions can only be requested for approved requests expiring within 30 days.

Deprecated: Use RequestExtensionWithContext for context cancellation support.

func (*Client) RequestExtensionWithContext added in v1.3.0 

func (c *Client) RequestExtensionWithContext(ctx context.Context, requestID string) (*RequestsInfo, error)

RequestExtensionWithContext submits a request to extend access for a zone request. Extensions can only be requested for approved requests expiring within 30 days.

func (*Client) RequestTLDs deprecated 

func (c *Client) RequestTLDs(tlds []string, reason string) error

RequestTLDs is a helper function that requests access to the specified TLDs with the provided reason. The TLDs should be marked as available for request from GetTLDStatus(). It automatically retrieves the current terms and conditions before submitting the request.

Deprecated: Use RequestTLDsWithContext for context cancellation support.

func (*Client) RequestTLDsWithContext added in v1.3.0 

func (c *Client) RequestTLDsWithContext(ctx context.Context, tlds []string, reason string) error

RequestTLDsWithContext is a helper function that requests access to the specified TLDs with the provided reason. It automatically retrieves the current terms and conditions before submitting the request.

func (*Client) SetLogger added in v1.2.9 

func (c *Client) SetLogger(l Logger)

SetLogger enables verbose printing for most API calls with the provided logger. Defaults to nil/off.

func (*Client) SubmitRequest deprecated 

func (c *Client) SubmitRequest(request *RequestSubmission) error

SubmitRequest submits a new request for access to specified zones. The request must include valid terms and conditions version and reason.

Deprecated: Use SubmitRequestWithContext for context cancellation support.

func (*Client) SubmitRequestWithContext added in v1.3.0 

func (c *Client) SubmitRequestWithContext(ctx context.Context, request *RequestSubmission) error

SubmitRequestWithContext submits a new request for access to specified zones. The request must include valid terms and conditions version and reason.

type Credentials 

type Credentials struct {
	Username string `json:"username"`
	Password string `json:"password"`
}

Credentials used by the czds.Client

func (Credentials) GoString added in v1.3.0 

func (c Credentials) GoString() string

GoString returns a Go-syntax representation with password redacted, used by %#v and %+v formatting.

func (Credentials) String added in v1.3.0 

func (c Credentials) String() string

String returns a string representation of credentials with the password redacted for security.

type DownloadInfo 

type DownloadInfo struct {
	ContentLength int64
	LastModified  time.Time
	Filename      string
}

DownloadInfo contains information from the HEAD request from a DownloadLink

type FtpDetails 

type FtpDetails struct {
	PrivateDataError bool `json:"privateDataError"`
}

FtpDetails contains FTP information for RequestsInfo.

type HistoryEntry 

type HistoryEntry struct {
	Timestamp time.Time `json:"timestamp"`
	Action    string    `json:"action"`
	Comment   string    `json:"comment"`
}

HistoryEntry contains a timestamp and description of an action that happened for a RequestsInfo. For example: requested, expired, approved, etc.

type Logger added in v1.2.9 

type Logger interface {
	Printf(format string, v ...any)
}

Logger specifies the methods required for the verbose logger for the API

type Request 

type Request struct {
	RequestID   string    `json:"requestId"`
	TLD         string    `json:"tld"`
	ULabel      string    `json:"ulable"` // ULabel contains UTF-8 decoded punycode (API appears to have a typo in the field name)
	Status      string    `json:"status"` // Status should be set to one of the Request* constants
	Created     time.Time `json:"created"`
	LastUpdated time.Time `json:"last_updated"`
	Expired     time.Time `json:"expired"` // Expired time; epoch 0 means no expiration set
	SFTP        bool      `json:"sftp"`
	AutoRenew   bool      `json:"auto_renew"`
}

Request holds information about a request in RequestsResponse from GetRequests()

type RequestSubmission 

type RequestSubmission struct {
	AllTLDs          bool     `json:"allTlds"`
	TLDNames         []string `json:"tldNames"`
	Reason           string   `json:"reason"`
	TcVersion        string   `json:"tcVersion"` // terms and conditions revision version
	AdditionalFTPIps []string `json:"additionalFtfIps,omitempty"`
}

RequestSubmission contains the information required to submit a new request with SubmitRequest()

type RequestsFilter 

type RequestsFilter struct {
	Status     string             `json:"status"` // should be set to one of the Request* constants
	Filter     string             `json:"filter"` // zone name search
	Pagination RequestsPagination `json:"pagination"`
	Sort       RequestsSort       `json:"sort"`
}

RequestsFilter is used to set what results should be returned by GetRequests

type RequestsInfo 

type RequestsInfo struct {
	RequestID          string         `json:"requestId"`
	TLD                *TLDStatus     `json:"tld"`
	FtpIps             []string       `json:"ftpips"`
	Status             string         `json:"status"` // should be set to one of the Status* constants
	TcVersion          string         `json:"tcVersion"`
	Created            time.Time      `json:"created"`
	RequestIP          string         `json:"requestIp"`
	Reason             string         `json:"reason"`
	LastUpdated        time.Time      `json:"last_updated"`
	Cancellable        bool           `json:"cancellable"`
	Extensible         bool           `json:"extensible"`
	ExtensionInProcess bool           `json:"extensionInProcess"`
	AutoRenew          bool           `json:"auto_renew"`
	Expired            time.Time      `json:"expired"` // Note: epoch 0 means no expiration set.
	History            []HistoryEntry `json:"history"`
	FtpDetails         *FtpDetails    `json:"ftpDetails"`
	PrivateDataError   bool           `json:"privateDataError"`
}

RequestsInfo contains the detailed information about a particular zone request returned by GetRequestInfo()

type RequestsPagination 

type RequestsPagination struct {
	Size int `json:"size"`
	Page int `json:"page"`
}

RequestsPagination sets the page size and offset for paginated results for RequestsFilter

type RequestsResponse 

type RequestsResponse struct {
	Requests      []Request `json:"requests"`
	TotalRequests int64     `json:"totalRequests"`
}

RequestsResponse holds Requests from GetRequests() and total number of requests that match the query but may not be returned due to pagination

type RequestsSort 

type RequestsSort struct {
	Field     string `json:"field"`
	Direction string `json:"direction"`
}

RequestsSort sets which field and direction the results for the RequestsFilter request should be returned with

type TLDStatus 

type TLDStatus struct {
	TLD           string `json:"tld"`
	ULabel        string `json:"ulable"`        // ULabel contains UTF-8 decoded punycode (API appears to have a typo in the field name)
	CurrentStatus string `json:"currentStatus"` // CurrentStatus should be set to one of the Status* constants
	SFTP          bool   `json:"sftp"`
}

TLDStatus is information about a particular TLD returned from GetTLDStatus() or included in RequestsInfo

type Terms 

type Terms struct {
	Version    string    `json:"version"`
	Content    string    `json:"content"`
	ContentURL string    `json:"contentUrl"`
	Created    time.Time `json:"created"`
}

Terms holds the terms and conditions details from GetTerms()

Source Files

View all Source files

Directories

Path Synopsis
cmd
Package main provides the czds command-line tool for interacting with ICANN's Centralized Zone Data Service (CZDS).
 Package main provides the czds command-line tool for interacting with ICANN's Centralized Zone Data Service (CZDS).
webhook
Package webhook provides a generic HTTP webhook client for batch download approval and notifications.
 Package webhook provides a generic HTTP webhook client for batch download approval and notifications.
Package jwt defines the JWT types used by the CZDS authentication API.
 Package jwt defines the JWT types used by the CZDS authentication API.

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.