api

type Auth interface {
	// New uses the authentication information to create a Handle.
	New(ppfmt pp.PP, options HandleOptions) (Handle, bool)

	// CheckUsability performs an early credential usability check.
	//
	// The check is warning-only and should not block startup.
	CheckUsability(ctx context.Context, ppfmt pp.PP)
}

type CloudflareAuth struct {
	Token   string
	BaseURL string
}

type DeletionMode bool

type Handle interface {
	// ListRecords lists managed DNS records matching the given domain/IP-family scope.
	// The managed-record selector is bound into the handle options because
	// implementations may cache filtered records by domain/IP-family scope.
	//
	// The second return value indicates whether the list was cached.
	ListRecords(ctx context.Context, ppfmt pp.PP, ipFamily ipnet.Family, domain domain.Domain,
		fallbackParams RecordParams,
	) ([]Record, bool, bool)

	// UpdateRecord reconciles one managed DNS record to the desired state.
	//
	// Implementations must apply the desired DNS content and metadata in
	// desiredParams for this record:
	// - content/IP: ip
	// - ttl/proxied/comment/tags: desiredParams
	UpdateRecord(ctx context.Context, ppfmt pp.PP, ipFamily ipnet.Family, domain domain.Domain,
		id ID, ip netip.Addr, desiredParams RecordParams,
	) bool

	// CreateRecord creates one managed DNS record with the given desired metadata.
	// It returns the ID of the new record.
	CreateRecord(ctx context.Context, ppfmt pp.PP, ipFamily ipnet.Family, domain domain.Domain,
		ip netip.Addr, desiredParams RecordParams) (ID, bool)

	// DeleteRecord deletes one managed DNS record by ID.
	//
	// mode controls cache invalidation behavior for failure handling.
	DeleteRecord(ctx context.Context, ppfmt pp.PP, ipFamily ipnet.Family,
		domain domain.Domain, id ID, mode DeletionMode,
	) bool

	// ListWAFListItems returns managed WAF list items with their IP ranges.
	// It does not create the list if it does not exist.
	//
	// The managed-item selector is bound into the handle options because
	// implementations may cache filtered items by WAF-list scope.
	// fallbackItemComment is the fallback comment target for newly created
	// managed list items; implementations may use it for advisory mismatch hints.
	//
	// 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, fallbackDescription, fallbackItemComment string,
	) ([]WAFListItem, bool, bool, bool)

	// FinalCleanWAFList removes managed WAF content during shutdown.
	// Implementations choose whole-list or managed-item cleanup from the handle's
	// bound ownership policy and the in-scope family set for the run.
	//
	// The handle should not be reused for any further update operations after
	// calling this method.
	FinalCleanWAFList(ctx context.Context, ppfmt pp.PP, list WAFList,
		fallbackDescription string, managedFamilies map[ipnet.Family]bool,
	) WAFListCleanupCode

	// DeleteWAFListItems deletes managed WAF list items by item IDs.
	DeleteWAFListItems(ctx context.Context, ppfmt pp.PP, list WAFList, fallbackDescription string, ids []ID) bool

	// CreateWAFListItems creates managed WAF list items with the given prefixes
	// and per-item comments.
	CreateWAFListItems(ctx context.Context, ppfmt pp.PP, list WAFList, fallbackDescription string,
		items []WAFListCreateItem) bool
}

type HandleOptions struct {
	HandleOwnershipPolicy

	CacheExpiration time.Duration
}

type HandleOwnershipPolicy struct {
	ManagedRecordsCommentRegex        *regexp.Regexp
	ManagedWAFListItemsCommentRegex   *regexp.Regexp
	AllowWholeWAFListDeleteOnShutdown bool
}

type ID string

type Record struct {
	ID           ID
	IP           netip.Addr
	RecordParams //nolint:embeddedstructfieldcheck // parameters go last
}

type RecordParams struct {
	TTL     TTL
	Proxied bool
	Comment string
	Tags    []string
}

type TTL int

type WAFList struct {
	AccountID ID
	Name      string
}

type WAFListCleanupCode int

type WAFListCreateItem struct {
	Prefix  netip.Prefix
	Comment string
}

type WAFListItem struct {
	ID      ID
	Prefix  netip.Prefix
	Comment string
}