{"id":15514722,"url":"https://github.com/fgasper/p5-dns-unbound","last_synced_at":"2025-03-28T19:21:34.163Z","repository":{"id":48071792,"uuid":"176630226","full_name":"FGasper/p5-DNS-Unbound","owner":"FGasper","description":"CPAN’s DNS::Unbound","archived":false,"fork":false,"pushed_at":"2023-02-03T02:09:27.000Z","size":413,"stargazers_count":1,"open_issues_count":2,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-02T20:51:08.435Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FGasper.png","metadata":{"files":{"readme":"README.md","changelog":"Changes","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-03-20T01:46:09.000Z","updated_at":"2022-06-01T12:21:23.000Z","dependencies_parsed_at":"2023-02-18T02:30:37.068Z","dependency_job_id":null,"html_url":"https://github.com/FGasper/p5-DNS-Unbound","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FGasper%2Fp5-DNS-Unbound","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FGasper%2Fp5-DNS-Unbound/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FGasper%2Fp5-DNS-Unbound/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FGasper%2Fp5-DNS-Unbound/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FGasper","download_url":"https://codeload.github.com/FGasper/p5-DNS-Unbound/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246085655,"owners_count":20721213,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-02T10:00:25.753Z","updated_at":"2025-03-28T19:21:34.141Z","avatar_url":"https://github.com/FGasper.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NAME\n\nDNS::Unbound - Query DNS recursively via [libunbound](https://www.nlnetlabs.nl/documentation/unbound/libunbound/)\n\n\u003cdiv\u003e\n    \u003ca href='https://coveralls.io/github/FGasper/p5-DNS-Unbound?branch=master'\u003e\u003cimg src='https://coveralls.io/repos/github/FGasper/p5-DNS-Unbound/badge.svg?branch=master' alt='Coverage Status' /\u003e\u003c/a\u003e\n\u003c/div\u003e\n\n# SYNOPSIS\n\n    my $dns = DNS::Unbound-\u003enew()-\u003eset_option( verbosity =\u003e 2 );\n\n    # This appears to be safe:\n    $dns-\u003eenable_threads();\n\n    my $verbosity = $dns-\u003eget_option( 'verbosity' );\n\n    $dns-\u003eset_option( verbosity =\u003e 1 + $verbosity );\n\nSynchronous queries:\n\n    my $res_hr = $dns-\u003eresolve( 'cpan.org', 'NS' );\n\n    # See below about encodings in “data”.\n    my @ns = map { $dns-\u003edecode_name($_) } @{ $res_hr-\u003edata() };\n\nAsynchronous queries use [the “Promise” pattern](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises). Assuming you’re using\nan off-the-shelf event loop, you can do something like:\n\n    my $dns = DNS::Unbound::AnyEvent-\u003enew();\n\n    my $query1 = $dns-\u003eresolve_async( 'usa.gov', 'A' )-\u003ethen(\n        sub { my $data = shift()-\u003edata(); ... },  # success handler\n        sub { ... },                              # failure handler\n    );\n\n    my $query2 = $dns-\u003eresolve_async( 'in-addr.arpa', 'NS' )-\u003ethen(\n        sub { ... },\n        sub { ... },\n    );\n\nYou can also integrate with a custom event loop; see [\"EVENT LOOPS\"](#event-loops) below.\n\n# DESCRIPTION\n\nTypical DNS lookups involve a request to a local server that caches\ninformation from DNS. The caching makes it fast, but it also means\nupdates to DNS aren’t always available via that local server right away.\nMost applications don’t need to care and so can enjoy the speed of\ncached results.\n\nApplications that need up-to-date DNS query results, though, need\n_fully-recursive_ DNS queries. NLnet Labs’s\n[libunbound](https://www.nlnetlabs.nl/documentation/unbound/libunbound/)\nis a popular solution for such queries; the present Perl module is an\ninterface to that library.\n\n# CHARACTER ENCODING\n\nDNS doesn’t know about character encodings, so neither does Unbound.\nThus, all strings given to this module must be **byte** **strings**.\nAll returned strings will be byte strings as well.\n\n# EVENT LOOPS\n\nThis distribution includes the classes [DNS::Unbound::AnyEvent](https://metacpan.org/pod/DNS%3A%3AUnbound%3A%3AAnyEvent),\n[DNS::Unbound::IOAsync](https://metacpan.org/pod/DNS%3A%3AUnbound%3A%3AIOAsync), and [DNS::Unbound::Mojo](https://metacpan.org/pod/DNS%3A%3AUnbound%3A%3AMojo), which provide\nout-of-the-box compatibility with those popular event loop interfaces.\nYou should probably use one of these.\n\nYou can also integrate with a custom event loop via the `fd()` method\nof this class: wait for that file descriptor to be readable, then\ncall this class’s `perform()` method.\n\n# MEMORY LEAK DETECTION\n\nObjects in this namespace will, if left alive at global destruction,\nthrow a warning about memory leaks. To silence these warnings, either\nallow all queries to complete, or cancel queries you no longer care about.\n\n# ERRORS\n\nThis library throws 3 kinds of errors:\n\n- Plain strings. Generally thrown in “simple” failure cases,\ne.g., invalid inputs.\n- [DNS::Unbound::X::Unbound](https://metacpan.org/pod/DNS%3A%3AUnbound%3A%3AX%3A%3AUnbound) instances. Thrown whenever\nUnbound gives an error.\n- [DNS::Unbound::X::ResolveError](https://metacpan.org/pod/DNS%3A%3AUnbound%3A%3AX%3A%3AResolveError) instances. A subclass\nof the last kind, for (Unbound-reported) resolution failures.\n(This is **NOT** for DNS-reported failures.)\n\n# CONSTANTS\n\nThe following from `libunbound/context.h` are defined here:\n`UB_NOERROR`, `UB_SOCKET`, `UB_NOMEM`, `UB_SYNTAX`, `UB_SERVFAIL`,\n`UB_FORKFAIL`, `UB_AFTERFINAL`, `UB_INITFAIL`, `UB_PIPE`,\n`UB_READFILE`, `UB_NOID`\n\n# METHODS\n\n## _CLASS_-\u003enew()\n\nInstantiates this class.\n\n## $result\\_obj = _OBJ_-\u003eresolve( $NAME, $TYPE \\[, $CLASS \\] )\n\nRuns a synchronous query for a given $NAME and $TYPE. $TYPE may be\nexpressed numerically or, for convenience, as a string. $CLASS is\noptional and defaults to 1 (`IN`), which is probably what you want.\n\nReturns a [DNS::Unbound::Result](https://metacpan.org/pod/DNS%3A%3AUnbound%3A%3AResult) instance.\n\n**NOTE:** libunbound doesn’t seem to offer effective controls for\ntiming out a synchronous query.\nIf timeouts are relevant for you, you probably need\nto use `resolve_async()` instead.\n\n## $query\\_obj = _OBJ_-\u003eresolve\\_async( $NAME, $TYPE \\[, $CLASS \\] );\n\nLike `resolve()` but starts an asynchronous query rather than a\nsynchronous one.\n\nThis returns an instance of [DNS::Unbound::AsyncQuery](https://metacpan.org/pod/DNS%3A%3AUnbound%3A%3AAsyncQuery) (a subclass\nthereof, to be precise).\n\nIf you’re using one of the special event interface subclasses\n(e.g., [DNS::Unbound::IOAsync](https://metacpan.org/pod/DNS%3A%3AUnbound%3A%3AIOAsync)) then the returned promise will resolve\nas part of the event loop’s normal operation. Otherwise,\n[see below](#custom-event-loop-integration) for the methods you’ll need\nto use in tandem with this one to get your query result.\n\n## _OBJ_-\u003eenable\\_threads()\n\nSets _OBJ_’s asynchronous queries to use threads rather than forking.\nOff by default. Throws an exception if called after an asynchronous query has\nalready been sent.\n\nReturns _OBJ_.\n\n## _OBJ_-\u003eset\\_option( $NAME =\u003e $VALUE )\n\nSets a configuration option. Returns _OBJ_.\n\nNote that this is basically just a passthrough to the underlying\n`ub_ctx_set_option()` function and is thus subject to the same limitations\nas that function; for example, you can’t set `verbosity` after the\nconfiguration has been “finalized”. (So use `debuglevel()` for that\ninstead.)\n\n## $value = _OBJ_-\u003eget\\_option( $NAME )\n\nGets a configuration option’s value.\n\n## _OBJ_-\u003edebuglevel( $LEVEL )\n\nSets the debug level (an integer). Returns _OBJ_.\n\nAs of libunbound v1.9.2, this is just a way to set the `verbosity`\noption regardless of whether the configuration is finalized.\n\n## _OBJ_-\u003edebugout( $FD\\_OR\\_FH )\n\nAccepts a file descriptor or Perl filehandle and designates that\nas the destination for libunbound diagnostic information.\n\nReturns _OBJ_.\n\n## $str = _CLASS_-\u003eunbound\\_version()\n\nGives the libunbound version string.\n\n# METHODS FOR ALTERING RESOLVER LOGIC\n\nThe following parallel their equivalents in libunbound.\nThey return _OBJ_ and throw errors on failure.\n\n## _OBJ_-\u003ehosts( $FILENAME )\n\n\n\n## _OBJ_-\u003eresolveconf( $FILENAME )\n\n\n\n# CUSTOM EVENT LOOP INTEGRATION\n\nUnless otherwise noted, the following methods correspond to their\nequivalents in libunbound. They return the same values as the\nlibunbound equivalents.\n\nYou don’t need these if you use one of the event loop subclasses\n(which is recommended).\n\n## _OBJ_-\u003epoll()\n\n\n\n## _OBJ_-\u003efd()\n\n\n\n## _OBJ_-\u003ewait()\n\n\n\n## _OBJ_-\u003eprocess()\n\n\n\n## _OBJ_-\u003ecount\\_pending\\_queries()\n\nReturns the number of outstanding asynchronous queries.\n\n# METHODS FOR DEALING WITH DNSSEC\n\nThe following correspond to their equivalents in libunbound\nand will only work if the underlying libunbound version supports them.\n\nThey return _OBJ_ and throw errors on failure.\n\n## _OBJ_-\u003eadd\\_ta( $TA )\n\n\n\n## _OBJ_-\u003eadd\\_ta\\_autr( $PATH )\n\n(Available only if libunbound supports it.)\n\n## _OBJ_-\u003eadd\\_ta\\_file( $PATH )\n\n\n\n## _OBJ_-\u003etrustedkeys( $PATH )\n\n\n\n# CONVENIENCE FUNCTIONS\n\nThe following may be called either as object methods or as static\nfunctions (but not as class methods). In addition to these,\n[Socket](https://metacpan.org/pod/Socket) provides the `inet_ntoa()` and `inet_ntop()`\nfunctions for decoding the values of `A` and `AAAA` records.\n\n**NOTE:** Consider parsing [DNS::Unbound::Result](https://metacpan.org/pod/DNS%3A%3AUnbound%3A%3AResult)’s `answer_packet()`\nas a more robust, albeit heavier, way to parse query result data.\n[Net::DNS::Packet](https://metacpan.org/pod/Net%3A%3ADNS%3A%3APacket) and [AnyEvent::DNS](https://metacpan.org/pod/AnyEvent%3A%3ADNS)’s `dns_unpack()` are two good\nways to parse DNS packets.\n\n## $decoded = decode\\_name($encoded)\n\nDecodes a DNS name. Useful for, e.g., `NS`, `CNAME`, and `PTR` query\nresults.\n\nNote that this function’s return will normally include a trailing `.`\nbecause of the trailing NUL byte in an encoded DNS name. This is normal\nand expected.\n\n## $strings\\_ar = decode\\_character\\_strings($encoded)\n\nDecodes a list of character-strings into component strings,\nreturned as an array reference. Useful for `TXT` query results.\n\n# SEE ALSO\n\n[Net::DNS::Resolver::Recurse](https://metacpan.org/pod/Net%3A%3ADNS%3A%3AResolver%3A%3ARecurse) provides comparable logic to this module\nin pure Perl. Like Unbound, it is maintained by\n[NLnet Labs](https://nlnetlabs.nl/).\n\n[Net::DNS::Resolver::Unbound](https://metacpan.org/pod/Net%3A%3ADNS%3A%3AResolver%3A%3AUnbound) is another XS binding to Unbound,\nimplemented as a subclass of [Net::DNS::Resolver](https://metacpan.org/pod/Net%3A%3ADNS%3A%3AResolver).\n\n# LICENSE \u0026 COPYRIGHT\n\nCopyright 2019-2022 Gasper Software Consulting.\n\nThis library is licensed under the same terms as Perl itself.\n\n# REPOSITORY\n\n[https://github.com/FGasper/p5-DNS-Unbound](https://github.com/FGasper/p5-DNS-Unbound)\n\n# THANK YOU\n\nSpecial thanks to [ATOOMIC](https://metacpan.org/author/ATOOMIC) for\nmaking some helpful review notes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffgasper%2Fp5-dns-unbound","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffgasper%2Fp5-dns-unbound","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffgasper%2Fp5-dns-unbound/lists"}