libdns

type Address struct {
	Name string
	TTL  time.Duration
	IP   netip.Addr

	// Optional custom data associated with the provider serving this record.
	// See the package godoc for important details on this field.
	ProviderData any
}

type AtomicErr error

type CAA struct {
	Name  string
	TTL   time.Duration
	Flags uint8 // As of March 2025, the only valid values are 0 and 128.
	Tag   string
	Value string

	// Optional custom data associated with the provider serving this record.
	// See the package godoc for important details on this field.
	ProviderData any
}

type CNAME struct {
	Name   string
	TTL    time.Duration
	Target string

	// Optional custom data associated with the provider serving this record.
	// See the package godoc for important details on this field.
	ProviderData any
}

type MX struct {
	Name       string
	TTL        time.Duration
	Preference uint16 // Lower values indicate that clients should prefer this server. This field is similar to the “Priority” field in SRV records.
	Target     string // The hostname of the mail server

	// Optional custom data associated with the provider serving this record.
	// See the package godoc for important details on this field.
	ProviderData any
}

type NS struct {
	Name   string
	TTL    time.Duration
	Target string

	// Optional custom data associated with the provider serving this record.
	// See the package godoc for important details on this field.
	ProviderData any
}

type RR struct {
	// The name of the record. It is partially qualified, relative to the zone.
	// For the sake of consistency, use "@" to represent the root of the zone.
	// An empty name typically refers to the last-specified name in the zone
	// file, which is only determinable in specific contexts.
	//
	// (For the following examples, assume the zone is “example.com.”)
	//
	// Examples:
	//   - “www” (for “www.example.com.”)
	//   - “@” (for “example.com.”)
	//   - “subdomain” (for “subdomain.example.com.”)
	//   - “sub.subdomain” (for “sub.subdomain.example.com.”)
	//
	// Invalid:
	//   - “www.example.com.” (fully-qualified)
	//   - “example.net.” (fully-qualified)
	//   - "" (empty)
	//
	// Valid, but probably doesn't do what you want:
	//   - “www.example.net” (refers to “www.example.net.example.com.”)
	Name string `json:"name"`

	// The time-to-live of the record. This is represented in the DNS zone file as
	// an unsigned integral number of seconds, but is provided here as a
	// [time.Duration] for ease of use in Go code. Fractions of seconds will be
	// rounded down (truncated). A value of 0 means that the record should not be
	// cached. Some provider implementations may assume a default TTL from 0; to
	// avoid this, set TTL to a sub-second duration.
	//
	// Note that some providers may reject or silently increase TTLs that are below
	// a certain threshold, and that DNS resolvers may choose to ignore your TTL
	// settings, so it is recommended to not rely on the exact TTL value.
	TTL time.Duration `json:"ttl"`

	// The type of the record as an uppercase string. DNS provider packages are
	// encouraged to support as many of the most common record types as possible,
	// especially: A, AAAA, CNAME, TXT, HTTPS, and SRV.
	//
	// Other custom record types may be supported with implementation-defined
	// behavior.
	Type string `json:"type"`

	// The data (or "value") of the record. This field should be formatted in
	// the *unescaped* standard zone file syntax (technically, the "RDATA" field
	// as defined by RFC 1035 §5.1). Due to variances in escape sequences and
	// provider support, this field should not contain escapes. More concretely,
	// the following [libdns.Record]s
	//
	//  []libdns.TXT{
	//      {
	//          Name: "alpha",
	//          Text: `quotes " backslashes \000`,
	//      }, {
	//          Name: "beta",
	//          Text: "del: \x7F",
	//      },
	//  }
	//
	// should be equivalent to the following in zone file syntax:
	//
	//  alpha  0  IN  TXT  "quotes \" backslashes \\000"
	//  beta   0  IN  TXT  "del: \177"
	//
	// Implementations are not expected to support RFC 3597 “\#” escape
	// sequences, but may choose to do so if they wish.
	Data string `json:"data"`
}

type Record interface {
	RR() RR
}

type RecordAppender interface {
	// AppendRecords creates the inputted records in the given zone and returns
	// the populated records that were created. It never changes existing records.
	//
	// Therefore, it makes little sense to use this method with CNAME-type
	// records since if there are no existing records with the same name, it
	// behaves the same as [libdns.RecordSetter.SetRecords], and if there are
	// existing records with the same name, it will either fail or leave the
	// zone in an invalid state.
	//
	// Implementations should return struct types defined by this package which
	// correspond with the specific RR-type (instead of the opaque [RR] struct).
	//
	// Implementations must honor context cancellation and be safe for concurrent
	// use.
	AppendRecords(ctx context.Context, zone string, recs []Record) ([]Record, error)
}

type RecordDeleter interface {
	// DeleteRecords deletes the given records from the zone if they exist in the
	// zone and exactly match the input. If the input records do not exist in the
	// zone, they are silently ignored. DeleteRecords returns only the the records
	// that were deleted, and does not return any records that were provided in the
	// input but did not exist in the zone.
	//
	// DeleteRecords only deletes records from the zone that *exactly* match the
	// input records—that is, the name, type, TTL, and value all must be identical
	// to a record in the zone for it to be deleted.
	//
	// As a special case, you may leave any of the fields [libdns.Record.Type],
	// [libdns.Record.TTL], or [libdns.Record.Value] empty ("", 0, and ""
	// respectively). In this case, DeleteRecords will delete any records that
	// match the other fields, regardless of the value of the fields that were left
	// empty. Note that this behavior does *not* apply to the [libdns.Record.Name]
	// field, which must always be specified.
	//
	// Note that it is semantically invalid to remove the last “NS” record from a
	// zone, so attempting to do is undefined behavior.
	//
	// Implementations should return struct types defined by this package which
	// correspond with the specific RR-type (instead of the opaque [RR] struct).
	//
	// Implementations must honor context cancellation and be safe for concurrent
	// use.
	DeleteRecords(ctx context.Context, zone string, recs []Record) ([]Record, error)
}

type RecordGetter interface {
	// GetRecords returns all the records in the DNS zone.
	//
	// DNSSEC-related records are typically not included in the output, but this
	// behavior is implementation-defined. If an implementation includes DNSSEC
	// records in the output, this behavior should be documented.
	//
	// Implementations must honor context cancellation and be safe for concurrent
	// use.
	GetRecords(ctx context.Context, zone string) ([]Record, error)
}

type RecordSetter interface {
	// SetRecords updates the zone so that the records described in the input are
	// reflected in the output. It may create or update records or—depending on
	// the record type—delete records to maintain parity with the input. No other
	// records are affected. It returns the records which were set.
	//
	// For any (name, type) pair in the input, SetRecords ensures that the only
	// records in the output zone with that (name, type) pair are those that were
	// provided in the input.
	//
	// In RFC 9499 terms, SetRecords appends, modifies, or deletes records in the
	// zone so that for each RRset in the input, the records provided in the input
	// are the only members of their RRset in the output zone.
	//
	// SetRecords is distinct from [libdns.RecordAppender.AppendRecords] in that
	// AppendRecords *only* adds records to the zone, while SetRecords may also
	// delete records if necessary. Therefore, SetRecords behaves similarly to
	// the following code:
	//
	//	func SetRecords(ctx context.Context, zone string, recs []Record) ([]Record, error) {
	//		prevs, _ := p.GetRecords(ctx, zone)
	//		toDelete := []Record{}
	//		for _, prev := range prevs {
	//			for _, new := range recs {
	//				if prev.RR().Name == new.RR().Name && prev.RR().Type == new.RR().Type {
	//					toDelete = append(toDelete, prev)
	//				}
	//			}
	//		}
	//		DeleteRecords(ctx, zone, toDelete)
	//		return AppendRecords(ctx, zone, recs)
	//	}
	//
	// Implementations may decide whether or not to support DNSSEC-related records
	// in calls to SetRecords, but should document their decision. Note that the
	// decision to support DNSSEC records in SetRecords is independent of the
	// decision to support them in [libdns.RecordGetter.GetRecords], so callers
	// should not blindly call SetRecords with the output of
	// [libdns.RecordGetter.GetRecords].
	//
	// If possible, implementations should make SetRecords atomic, such that if
	// err == nil, then all of the requested changes were made, and if err != nil,
	// then the zone remains as if the method was never called. However, as very
	// few providers offer batch/atomic operations, the actual result of a call
	// where err != nil is undefined. Implementations may implement synthetic
	// atomicity that rolls back partial changes on failure ONLY if it can be
	// done reliably. For calls that error atomically, implementations should
	// return [AtomicErr] as the error so callers may know that their zone remains
	// in a consistent state. Implementations should document their atomicity
	// guarantees (or lack thereof).
	//
	// If SetRecords is used to add a CNAME record to a name with other existing
	// non-DNSSEC records, implementations may either fail with an error, add
	// the CNAME and leave the other records in place (in violation of the DNS
	// standards), or add the CNAME and remove the other preexisting records.
	// Therefore, users should proceed with caution when using SetRecords with
	// CNAME records.
	//
	// Implementations should return struct types defined by this package which
	// correspond with the specific RR-type (instead of the opaque [RR] struct).
	//
	// Implementations must honor context cancellation and be safe for concurrent
	// use.
	//
	// # Examples
	//
	// Example 1:
	//
	//	;; Original zone
	//	example.com. 3600 IN A   192.0.2.1
	//	example.com. 3600 IN A   192.0.2.2
	//	example.com. 3600 IN TXT "hello world"
	//
	//	;; Input
	//	example.com. 3600 IN A   192.0.2.3
	//
	//	;; Resultant zone
	//	example.com. 3600 IN A   192.0.2.3
	//	example.com. 3600 IN TXT "hello world"
	//
	// Example 2:
	//
	//	;; Original zone
	//	alpha.example.com. 3600 IN AAAA 2001:db8::1
	//	alpha.example.com. 3600 IN AAAA 2001:db8::2
	//	beta.example.com.  3600 IN AAAA 2001:db8::3
	//	beta.example.com.  3600 IN AAAA 2001:db8::4
	//
	//	;; Input
	//	alpha.example.com. 3600 IN AAAA 2001:db8::1
	//	alpha.example.com. 3600 IN AAAA 2001:db8::2
	//	alpha.example.com. 3600 IN AAAA 2001:db8::5
	//
	//	;; Resultant zone
	//	alpha.example.com. 3600 IN AAAA 2001:db8::1
	//	alpha.example.com. 3600 IN AAAA 2001:db8::2
	//	alpha.example.com. 3600 IN AAAA 2001:db8::5
	//	beta.example.com.  3600 IN AAAA 2001:db8::3
	//	beta.example.com.  3600 IN AAAA 2001:db8::4
	SetRecords(ctx context.Context, zone string, recs []Record) ([]Record, error)
}

type SRV struct {
	// “Service” is the name of the service being offered, without the leading
	// underscore. The correct value for this field is defined by the service
	// that you are serving (and is typically registered with IANA). Some
	// examples include "sip", "xmpp", "ldap", "minecraft", "stun", "turn", etc.
	Service string

	// “Transport” is the name of the transport protocol used by the service,
	// without the leading underscore. This is almost always "tcp" or "udp", but
	// "sctp" and "dccp" are technically valid as well.
	//
	// Note that RFC 2782 defines this field as “Proto[col]”, but we're using
	// the updated name “Transport” from RFC 6335 in order to avoid confusion
	// with the similarly-named field in the SVCB record type.
	Transport string

	Name     string
	TTL      time.Duration
	Priority uint16 // Lower values indicate that clients should prefer this server
	Weight   uint16 // Higher values indicate that clients should prefer this server when choosing between targets with the same priority
	Port     uint16 // The port on which the service is running.
	Target   string // The hostname of the server providing the service, which must not point to a CNAME.

	// Optional custom data associated with the provider serving this record.
	// See the package godoc for important details on this field.
	ProviderData any
}

type ServiceBinding struct {
	// “Scheme” is the scheme of the URL used to access the service, or some
	// other protocol identifier registered with IANA. This field should not
	// contain a leading underscore.
	//
	// If the scheme is set to "https", then a HTTPS-type record will be
	// generated; for all other schemes, a SVCB-type record will be generated.
	// As defined in RFC 9460, the schemes "http", "wss", and "ws" also map to
	// HTTPS records.
	//
	// Note that if a new SVCB-compatible RR type is defined and specified as
	// mapping to a scheme, then [libdns] may automatically generate that type
	// instead of SVCB at some point in the future. It is expected that any RFC
	// that proposes such a new type will ensure that this does not cause any
	// backwards compatibility issues.
	Scheme string

	// Warning: This field almost certainly does not do what you expect, and
	// should typically be unset (or set to 0).
	//
	// “URLSchemePort” is the port number that is explictly specified in a URL
	// when accessing a service. This field does not affect the port number that
	// is actually used to access the service, and unlike with SRV records, it
	// must be unset if you are using the default port for the scheme.
	//
	// # Examples
	//
	// In the typical case, you would have the following URL:
	//
	//  https://example.com/
	//
	// and then the client would lookup the following records:
	//
	//  example.com.  60  IN  HTTPS  1  example.net.  alpn=h2,h3
	//  example.net.  60  IN  A      192.0.2.1
	//
	// and then the client would connect to 192.0.2.1:443. But if you had the
	// same URL but the following records:
	//
	//  example.com.  60  IN  HTTPS  1  example.net.  alpn=h2,h3 port=1111
	//  example.net.  60  IN  A      192.0.2.2
	//
	// then the client would connect to 192.0.2.2:1111. But if you had the
	// following URL:
	//
	//  https://example.com:2222/
	//
	// then the client would lookup the following records:
	//
	//  _2222._https.example.com.  60  IN  HTTPS  1  example.net.  alpn=h2,h3
	//  example.net.               60  IN  A      192.0.2.3
	//
	// and the client would connect to 192.0.2.3:2222. And if you had the same
	// URL but the following records:
	//
	//  _2222._https.example.com.  60  IN  HTTPS  1  example.net.  alpn=h2,h3 port=3333
	//  example.net.               60  IN  A      192.0.2.4
	//
	// then the client would connect to 192.0.2.4:3333.
	//
	// So the key things to note here are that:
	//
	//  - If you want to change the port that the client connects to, you need
	//    to set the “port=” value in the “Params” field, not the
	//    “URLSchemePort”.
	//
	//  - The client will never lookup the HTTPS record prefixed with the
	//    underscored default port, so you should only set “URLSchemePort” if
	//    you are explicitly using a non-default port in the URL.
	//
	//  - It is completely valid to set the “port=” value in the “Params” field
	//    to the default port for the scheme, but also completely unnecessary.
	//
	//  - The “URLSchemePort” field and the “port=” value in the “Params” field
	//    are completely independent, with one exception: if you set the
	//    “URLSchemePort” field to a non-default port and leave the “port=”
	//    value in the “Params” field unset, then the client will default to the
	//    value of the “URLSchemePort” field, and not to the default port for
	//    the scheme.
	URLSchemePort uint16

	Name string
	TTL  time.Duration

	// “Priority” is the priority of the service, with lower values indicating
	// that clients should prefer this service over others.
	//
	// Note that Priority==0 is a special case, and indicates that the record
	// is an “Alias” record. Alias records behave like CNAME records, but are
	// allowed at the root of a zone. When in Alias mode, the Params field
	// should be unset.
	Priority uint16

	// “Target” is the target of the service, which is typically a hostname or
	// an alias (CNAME or other SVCB record). If this field is set to a single
	// dot ".", then the target is the same as the name of the record (without
	// the underscore-prefixed components, of course).
	Target string

	// “Params” is a map of key–value pairs that are used to specify various
	// parameters for the service. The keys are typically registered with IANA,
	// and which keys are valid is service-dependent.
	// https://www.iana.org/assignments/dns-svcb/dns-svcb.xhtml
	//
	// Note that there is a key called “mandatory”, but this does not mean that
	// it is mandatory for you to set the listed keys. Instead, this means that
	// if a client does not understand all of the listed keys, then it must
	// ignore the entire record. This is similar to the “critical” flag in CAA
	// records.
	Params SvcParams

	// Optional custom data associated with the provider serving this record.
	// See the package godoc for important details on this field.
	ProviderData any
}

type SvcParams map[string][]string

type TXT struct {
	Name string
	TTL  time.Duration

	// The “Text” field contains the arbitrary data associated with the TXT
	// record. The contents of this field should *not* be wrapped in quotes as
	// libdns implementations are expected to quote any fields as necessary. In
	// addition, as discussed in the description of [libdns.RR.Data], you should
	// not include any escaped characters in this field, as libdns will escape
	// them for you.
	//
	// In the zone file format and the DNS wire format, a single TXT record is
	// composed of one or more strings of no more than 255 bytes each ([RFC 1035
	// §3.3.14], [RFC 7208 §3.3]). We eschew those restrictions here, and
	// instead treat the entire TXT as a single, arbitrary-length string. libdns
	// implementations are therefore expected to handle this as required by
	// their respective DNS provider APIs. See the [DNSControl explainer] on
	// this for more information.
	//
	// [RFC 1035 §3.3.14]: https://datatracker.ietf.org/doc/html/rfc1035#section-3.3.14
	// [RFC 7208 §3.3]: https://datatracker.ietf.org/doc/html/rfc7208#section-3.3
	// [DNSControl explainer]: https://docs.dnscontrol.org/developer-info/opinions#opinion-8-txt-records-are-one-long-string
	Text string

	// Optional custom data associated with the provider serving this record.
	// See the package godoc for important details on this field.
	ProviderData any
}

type Zone struct {
	Name string
}

type ZoneLister interface {
	// ListZones returns the list of available DNS zones for use by other
	// [libdns] methods. Not every upstream provider API supports listing
	// available zones, and very few [libdns]-dependent packages use this
	// method, so this method is optional.
	//
	// Implementations must honor context cancellation and be safe for
	// concurrent use.
	ListZones(ctx context.Context) ([]Zone, error)
}