providers

type Capability int

type ConversionObserver interface {
	BeginToRC(function string, native any) ConversionSnapshot
	EndToRC(function string, before ConversionSnapshot, nativeAfter any, result models.Records, err error)
	BeginToNative(function string, records models.Records) ConversionSnapshot
	EndToNative(function string, before ConversionSnapshot, recordsAfter models.Records, result any, err error)
}

type ConversionSnapshot any

type CreateOption func(*CreateOptions)

type CreateOptions struct {
	ConversionObserver ConversionObserver
	// RequestedRole is set by the typed factory after caller options are applied.
	// It is exactly KindDNS or KindRegistrar for runtime instances.
	RequestedRole ProviderKind
}

type CredsField struct {
	// Key is the exact name of the field as it should appear inside the
	// creds.json provider entry (for example "apitoken" or "KeyId").
	Key string
	// Label is the human readable text shown when prompting.
	Label string
	// Help is a short sentence explaining the field.
	Help string
	// Secret masks the input when prompting. Ignored when Multiline is
	// also set, since the external editor does not mask input.
	Secret bool
	// Multiline opens the user's $EDITOR so values like PEM blocks with
	// embedded newlines can be entered in full.
	Multiline bool
	// Required makes the init command reject an empty value.
	Required bool
	// Default suggests a value. Presented as the pre filled answer.
	Default string
	// EnvVar, when set, is used as the default if the environment variable is
	// present. It overrides Default.
	EnvVar string
	// Choices restricts input to one of the listed values.
	Choices []string
	// ConfirmValue asks a yes/no question and stores this value on yes.
	ConfirmValue string
	// Validator can reject an entered value with an explanatory error.
	Validator func(string) error
	// Internal marks the field as a UI selector whose answer drives
	// ShowIf logic on later fields. Internal answers are not written to
	// creds.json.
	//
	// Convention: prefix the Key with an underscore (for example
	// "_authMethod") so it is visually distinct from real creds.json
	// keys when reading metadata registrations.
	Internal bool
	// ShowIf restricts when this field is shown. Each entry maps an
	// earlier field's Key to the value that must be selected for this
	// field to appear. An empty map means always show.
	ShowIf map[string]string
}

type DNSServiceProvider interface {
	models.DNSProvider
}

type Definition struct {
	// FriendlyName is the brand name ("Google", not "GCLOUD")
	FriendlyName string

	// Aliases (optional) is an optional list of aliases. For example, if
	// we rename CLOUDFLAREAPI to CLOUDFLARE, we would make CLOUDFLAREAPI an alias to
	// support legacy configurations.
	Aliases []string

	// Maintainer is the github username of the maintainer.
	Maintainer string

	// DefaultTTL (optional) minimum TTL when `get-zone` writes .js files
	DefaultTTL uint32

	// CredFields is a description of the creds.json fields for this provider. Used by "init".
	CredFields []CredsField

	// DocsURL optionally overrides https://docs.dnscontrol.org/provider/<lowercase name>
	// for legacy documentation paths. An override matching the default is an error.
	// Register fills an empty value with the default URL.
	DocsURL string
	// VendorAPIDocURL optionally links to the vendor's API documentation.
	VendorAPIDocURL string
	// PortalURL points to where a user can obtain API credentials.
	PortalURL string
	// Notes is optional onboarding text shown before prompting for credentials.
	Notes string
	// PostWrite prepares local resources after the wizard writes creds.json.
	PostWrite func(map[string]string) error

	// Nil capability notes fall back to Features. Explicit notes take precedence.
	CanAutoDNSSEC          *DocumentationNote
	CanConcur              *DocumentationNote
	CanUseDSForChildren    *DocumentationNote
	DocDualHost            *DocumentationNote
	DocOfficiallySupported *DocumentationNote
	RecordIdentity         RecordIdentityFunc
	Features               DocumentationNotes

	// SupportedTypes is an exhaustive declaration of record support. Nil means
	// Basic8 (A, AAAA, CAA, CNAME, MX, NS, SRV, TXT), except that non-nil
	// Features retains legacy validation. A non-nil empty slice declares no
	// support beyond Features.
	// Internal commands such as IMPORT_TRANSFORM do not belong in this list.
	SupportedTypes []string

	// Calculated by Register and Finalize. Providers must leave these fields unset.
	TypeName           string
	ImplementationType reflect.Type
	Kind               ProviderKind
	Initializer        Initializer
	RecordAuditor      RecordAuditor
	CanGetZones        bool
	DocCreateDomains   bool
	DerivedFeatures    DocumentationNotes
	// contains filtered or unexported fields
}

type DocumentationNote struct {
	HasFeature    bool
	Unimplemented bool
	Comment       string
	Link          string
}

type DocumentationNotes map[Capability]*DocumentationNote

type InitializableProvider interface {
	Initialize(map[string]string, json.RawMessage, *CreateOptions) error
}

type Initializer func(map[string]string, json.RawMessage, *CreateOptions) (any, error)

type None struct{}

type ProviderKind uint8

type RecordAuditor func(models.Records) []error

type RecordIdentityFunc func(*models.RecordConfig) string

type Registrar interface {
	models.Registrar
}

type ZoneCreator interface {
	EnsureZoneExists(dc *models.DomainConfig) error
}

type ZoneLister interface {
	ListZones() ([]string, error)
}