api

package
v1.15.1 Latest Latest
Warning

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

 Go to latest Published: Dec 16, 2024 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package api implements protocols to update DNS records.

Index

Constants

This section is empty.

Variables

View Source 
var WAFListMaxBitLen = map[ipnet.Type]int{
	ipnet.IP4: 32,
	ipnet.IP6: 64,
}

WAFListMaxBitLen records the maximum number of bits of an IP range/address Cloudflare can support in a WAF list.

According to the Cloudflare docs, an IP range/address in a list must be in one of the following formats: - An individual IPv4 address - An IPv4 CIDR ranges with a prefix from /8 to /32 - An IPv6 CIDR ranges with a prefix from /4 to /64 For this updater, only the maximum values matter.

Functions

This section is empty.

Types

type Auth 

type Auth interface {
	// New uses the authentication information to create a Handle.
	New(ppfmt pp.PP, cacheExpiration time.Duration) (Handle, bool)
}

An Auth contains authentication information.

type CloudflareAuth 

type CloudflareAuth struct {
	Token   string
	BaseURL string
}

A CloudflareAuth implements the Auth interface, holding the authentication data to create a CloudflareHandle.

func (CloudflareAuth) New 

func (t CloudflareAuth) New(ppfmt pp.PP, cacheExpiration time.Duration) (Handle, bool)

New creates a CloudflareHandle from the authentication data.

type CloudflareCache added in v1.8.0 

type CloudflareCache = struct {
	// contains filtered or unexported fields
}

CloudflareCache holds the previous repsonses from the Cloudflare API.

type CloudflareHandle 

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

A CloudflareHandle implements the Handle interface with the Cloudflare API.

func (CloudflareHandle) CreateRecord 

func (h CloudflareHandle) CreateRecord(ctx context.Context, ppfmt pp.PP,
	ipNet ipnet.Type, domain domain.Domain, ip netip.Addr, ttl TTL, proxied bool, recordComment string,
) (ID, bool)

CreateRecord calls cloudflare.CreateDNSRecord.

func (CloudflareHandle) CreateWAFListItems added in v1.14.0 

func (h CloudflareHandle) CreateWAFListItems(ctx context.Context, ppfmt pp.PP,
	list WAFList, expectedDescription string,
	itemsToCreate []netip.Prefix, comment string,
) bool

CreateWAFListItems calls cloudflare.CreateListItems.

func (CloudflareHandle) DeleteRecord 

func (h CloudflareHandle) DeleteRecord(ctx context.Context, ppfmt pp.PP,
	ipNet ipnet.Type, domain domain.Domain, id ID,
	mode DeletionMode,
) bool

DeleteRecord calls cloudflare.DeleteDNSRecord.

func (CloudflareHandle) DeleteWAFListItems added in v1.14.0 

func (h CloudflareHandle) DeleteWAFListItems(ctx context.Context, ppfmt pp.PP,
	list WAFList, expectedDescription string,
	ids []ID,
) bool

DeleteWAFListItems calls cloudflare.DeleteListItems.

func (CloudflareHandle) FinalClearWAFListAsync added in v1.14.1 

func (h CloudflareHandle) FinalClearWAFListAsync(ctx context.Context, ppfmt pp.PP,
	list WAFList, expectedDescription string,
) (bool, bool)

FinalClearWAFListAsync calls cloudflare.DeleteList and cloudflare.ReplaceListItemsAsync.

We only deleted cached data in listListItems and listID, but not the cached lists in listLists so that we do not have to re-query the lists under the same account. Managing multiple lists under the same account makes little sense in practice, but the tool should still do the right thing even under rare circumstances.

func (CloudflareHandle) FindWAFList added in v1.14.0 

func (h CloudflareHandle) FindWAFList(ctx context.Context, ppfmt pp.PP, list WAFList,
	expectedDescription string,
) (ID, bool)

FindWAFList returns the ID of the IP list with the given name.

func (CloudflareHandle) FlushCache 

func (h CloudflareHandle) FlushCache()

FlushCache flushes the API cache.

func (CloudflareHandle) ListRecords 

func (h CloudflareHandle) ListRecords(ctx context.Context, ppfmt pp.PP, ipNet ipnet.Type, domain domain.Domain,
) ([]Record, bool, bool)

ListRecords calls cloudflare.ListDNSRecords.

func (CloudflareHandle) ListWAFListItems added in v1.14.0 

func (h CloudflareHandle) ListWAFListItems(ctx context.Context, ppfmt pp.PP,
	list WAFList, expectedDescription string,
) ([]WAFListItem, bool, bool, bool)

ListWAFListItems calls cloudflare.ListListItems, and maybe cloudflare.CreateList when needed.

func (CloudflareHandle) ListWAFLists added in v1.14.0 

func (h CloudflareHandle) ListWAFLists(ctx context.Context, ppfmt pp.PP, accountID ID) ([]WAFListMeta, bool)

ListWAFLists lists all IP lists of the given name.

func (CloudflareHandle) ListZones added in v1.13.1 

func (h CloudflareHandle) ListZones(ctx context.Context, ppfmt pp.PP, name string) ([]ID, bool)

ListZones returns a list of zone IDs with the zone name.

func (CloudflareHandle) UpdateRecord 

func (h CloudflareHandle) UpdateRecord(ctx context.Context, ppfmt pp.PP,
	ipNet ipnet.Type, domain domain.Domain, id ID, ip netip.Addr,
	expectedTTL TTL, expectedProxied bool, expectedRecordComment string,
) bool

UpdateRecord calls cloudflare.UpdateDNSRecord.

func (CloudflareHandle) WAFListID added in v1.14.1 

func (h CloudflareHandle) WAFListID(ctx context.Context, ppfmt pp.PP, list WAFList,
	expectedDescription string,
) (ID, bool, bool)

WAFListID finds the ID of the list, if any. The second return value indicates whether the list is found.

func (CloudflareHandle) ZoneIDOfDomain added in v1.14.1 

func (h CloudflareHandle) ZoneIDOfDomain(ctx context.Context, ppfmt pp.PP, domain domain.Domain) (ID, bool)

ZoneIDOfDomain finds the active zone ID governing a particular domain.

type DeletionMode added in v1.14.1 

type DeletionMode bool

DeletionMode tells the deletion updater whether a careful re-reading of lists must be enforced if an error happens. 

const (
	// RegularDelitionMode enables re-reading when an error occurs.
	RegularDelitionMode DeletionMode = false
	// FinalDeletionMode disables re-reading when an error occurs.
	FinalDeletionMode DeletionMode = true
)

type Handle 

type Handle interface {
	// ListRecords lists all matching DNS records.
	//
	// The second return value indicates whether the list was cached.
	ListRecords(ctx context.Context, ppfmt pp.PP, ipNet ipnet.Type, domain domain.Domain) ([]Record, bool, bool)

	// UpdateRecord updates one DNS record.
	UpdateRecord(ctx context.Context, ppfmt pp.PP, ipNet ipnet.Type, domain domain.Domain, id ID, ip netip.Addr,
		expectedTTL TTL, expectedProxied bool, expectedRecordComment string,
	) bool

	// CreateRecord creates one DNS record. It returns the ID of the new record.
	CreateRecord(ctx context.Context, ppfmt pp.PP, ipNet ipnet.Type, domain domain.Domain,
		ip netip.Addr, ttl TTL, proxied bool, recordComment string) (ID, bool)

	// DeleteRecord deletes one DNS record, assuming we will not update or create any DNS records.
	DeleteRecord(ctx context.Context, ppfmt pp.PP, ipNet ipnet.Type, domain domain.Domain, id ID, mode DeletionMode) bool

	// ListWAFListItems retrieves a WAF list with IP rages.
	// It creates an empty WAF list with IP ranges if it does not already exist yet.
	// The first return value is the ID of the list.
	// The second return value indicates whether the list already exists.
	// The third return value indicates whether the list content was cached.
	ListWAFListItems(ctx context.Context, ppfmt pp.PP, list WAFList, expectedDescription string,
	) ([]WAFListItem, bool, bool, bool)

	// FinalClearWAFListAsync deletes or clears a WAF list with IP ranges, assuming we will not
	// update or create the list.
	//
	// The first return value indicates whether the list was deleted: If it's true, then it's deleted.
	// If it's false, then it's being cleared asynchronously instead of being deleted.
	//
	// The cache from list names to list IDs will not be cleared even if all deletion attempts fail.
	FinalClearWAFListAsync(ctx context.Context, ppfmt pp.PP, list WAFList, expectedDescription string,
	) (bool, bool)

	// DeleteWAFListItems deletes IP ranges from a WAF list.
	DeleteWAFListItems(ctx context.Context, ppfmt pp.PP, list WAFList, expectedDescription string,
		ids []ID) bool

	// CreateWAFListItems adds IP ranges to a WAF list.
	CreateWAFListItems(ctx context.Context, ppfmt pp.PP, list WAFList, expectedDescription string,
		items []netip.Prefix, comment string) bool
}

A Handle represents a generic API to update DNS records and WAF lists. Currently, the only implementation is Cloudflare.

type ID added in v1.14.0 

type ID string

ID is a new type representing identifiers to avoid programming mistakes.

func (ID) String added in v1.14.1 

func (id ID) String() string

type Record added in v1.14.0 

type Record struct {
	ID ID
	IP netip.Addr
}

Record bundles an ID and an IP address, representing a DNS record.

type TTL 

type TTL int

A TTL represents a time-to-live value of a DNS record. 

const TTLAuto TTL = 1

TTLAuto represents the "auto" value for Cloudflare servers.

func (TTL) Describe 

func (t TTL) Describe() string

Describe converts a TTL into a human-readable, user-friendly description that is suitable for printing.

func (TTL) Int 

func (t TTL) Int() int

Int converts a TTL into its raw integer value.

func (TTL) String 

func (t TTL) String() string

String converts a TTL into the string representation of its raw integer value.

type WAFList added in v1.14.0 

type WAFList struct {
	AccountID ID
	Name      string
}

WAFList represents a WAF list to update.

func (WAFList) Describe added in v1.14.0 

func (l WAFList) Describe() string

Describe formats WAFList as a string.

type WAFListItem added in v1.14.0 

type WAFListItem struct {
	ID     ID
	Prefix netip.Prefix
}

WAFListItem bundles an ID and an IP range, representing an item in a WAF list.

type WAFListMeta added in v1.14.1 

type WAFListMeta struct {
	ID          ID
	Name        string
	Description string
}

WAFListMeta contains the metadata of a list.

Source Files

View all Source files

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.