Top 0.1% dependent packages on proxy.golang.org
Top 0.2% dependent repos on proxy.golang.org
Top 3.9% forks on proxy.golang.org
Top 0.1% docker downloads on proxy.golang.org
proxy.golang.org : github.com/libdns/libdns
Package libdns defines core interfaces that should be implemented by packages that interact with DNS provider clients. These interfaces are small and idiomatic Go interfaces with well-defined semantics for the purposes of reading and manipulating DNS records using DNS provider APIs. This documentation uses the definitions for terms from RFC 9499: https://datatracker.ietf.org/doc/html/rfc9499 This package represents records with the Record interface, which is any type that can transform itself into the RR struct. This interface is implemented by the various record abstractions this package offers: RR structs, where the data is serialized as a single opaque string as if in a zone file, being a type-agnostic Resource Record (that is, a name, type, class, TTL, and data); and individual RR-type structures, where the data is parsed into its separate fields for easier manipulation by Go programs (for example: SRV, TXT, and ServiceBinding types). This hybrid design grants great flexibility for both DNS provider packages and consumer Go programs. Record values should not be primitvely compared (==) unless they are RR, because other struct types contain maps, for which equality is not defined; additionally, some packages may attach custom data to each RR struct-type's `ProviderData` field, whose values might not be comparable either. The `ProviderData` field is not portable across providers, or possibly even zones. Because it is not portable, and we want to ensure that RR structs remain both portable and comparable, the `RR()` method does not preserve `ProviderData` in its return value. Users of libdns packages should check the documentation of provider packages, as some may use the `ProviderData` field to reduce API calls / increase effiency. But implementations must never rely on `ProviderData` for correctness if possible (and should document clearly otherwise). Implementations of the libdns interfaces should accept as input any Record value, and should return as output the concrete struct types that implement the Record interface (i.e. Address, TXT, ServiceBinding, etc). This is important to ensure the provider libraries are robust and also predictable: callers can reliably type-switch on the output to immediately access structured data about each record without the possibility of errors. Returned values should be of types defined by this package to make type-assertions reliable. Records are described independently of any particular zone, a convention that grants records portability across zones. As such, record names are partially qualified, i.e. relative to the zone. For example, a record called “sub” in zone “example.com.” represents a fully-qualified domain name (FQDN) of “sub.example.com.”. Implementations should expect that input records conform to this standard, while also ensuring that output records do; adjustments to record names may need to be made before or after provider API calls, for example, to maintain consistency with all other libdns packages. Helper functions are available in this package to convert between relative and absolute names; see RelativeName and AbsoluteName. Although zone names are a required input, libdns does not coerce any particular representation of DNS zones; only records. Since zone name and records are separate inputs in libdns interfaces, it is up to the caller to maintain the pairing between a zone's name and its records. All interface implementations must be safe for concurrent/parallel use, meaning 1) no data races, and 2) simultaneous method calls must result in either both their expected outcomes or an error. For example, if libdns.RecordAppender.AppendRecords is called simultaneously, and two API requests are made to the provider at the same time, the result of both requests must be visible after they both complete; if the provider does not synchronize the writing of the zone file and one request overwrites the other, then the client implementation must take care to synchronize on behalf of the incompetent provider. This synchronization need not be global; for example: the scope of synchronization might only need to be within the same zone, allowing multiple requests at once as long as all of them are for different zone. (Exact logic depends on the provider.) Some service providers APIs may enforce rate limits or have sporadic errors. It is generally expected that libdns provider packages implement basic retry logic (e.g. retry up to 3-5 times with backoff in the event of a connection error or some HTTP error that may be recoverable, including 5xx or 429s) when it is safe to do so. Retrying/recovering from errors should not add substantial latency, though. If it will take longer than a couple seconds, best to return an error.
Registry
-
Source
- Documentation
- JSON
purl: pkg:golang/github.com/libdns/libdns
License: MIT
Latest release: 24 days ago
First release: about 5 years ago
Namespace: github.com/libdns
Dependent packages: 1,245
Dependent repositories: 1,063
Stars: 363 on GitHub
Forks: 70 on GitHub
Docker dependents: 971
Docker downloads: 943,295,317
Total Commits: 12
Committers: 3
Average commits per author: 4.0
Development Distribution Score (DDS): 0.167
More commit stats: commits.ecosyste.ms
See more repository details: repos.ecosyste.ms
Funding links: https://github.com/sponsors/mholt
Last synced: about 12 hours ago