Debian Codegraph @

src/shared/varlink-io.systemd.Resolve.Hook.c

raw
1 /* SPDX-License-Identifier: LGPL-2.1-or-later */
2
3 #include "varlink-io.systemd.Resolve.Hook.h"
4
5 /* We want to reuse the ResourceKey structure from the io.systemd.Resolve interface, hence import it here */
6 #include "varlink-io.systemd.Resolve.h"
7
8 static SD_VARLINK_DEFINE_STRUCT_TYPE(
9 Answer,
10 SD_VARLINK_FIELD_COMMENT("A resource record that shall be looked up. Note that this field is (currently) mostly "
11 "decoration, useful for debugging, and may be omitted. The data actually used is encoded in the "
12 "'raw' field."),
13 SD_VARLINK_DEFINE_FIELD_BY_TYPE(rr, ResourceRecord, SD_VARLINK_NULLABLE),
14 SD_VARLINK_FIELD_COMMENT("A resource record encoded in DNS wire format, in turn encoded in Base64. This is the actual data "
15 "returned to the application, and should carry the same information as the 'rr' field, just in a "
16 "different encoding."),
17 SD_VARLINK_DEFINE_FIELD(raw, SD_VARLINK_STRING, 0));
18
19 static SD_VARLINK_DEFINE_STRUCT_TYPE(
20 Question,
21 SD_VARLINK_FIELD_COMMENT("A resource record key that shall be looked up."),
22 SD_VARLINK_DEFINE_FIELD_BY_TYPE(key, ResourceKey, 0));
23
24 static SD_VARLINK_DEFINE_METHOD_FULL(
25 QueryFilter,
26 SD_VARLINK_SUPPORTS_MORE,
27 SD_VARLINK_FIELD_COMMENT("A list of domains this hook is interested in. Lookups for domains not listed here will not be "
28 "passed to the Hook via ResolveRecord(). If this field is not set, requests for all domains "
29 "will be passed to the hook. Note that this applies recursively, i.e. a domain of a lookup is "
30 "considered matching the listed domains both if it exactly matches it, and in case only a suffix "
31 "of it matches it. If this is set to an empty array the hook is disabled."),
32 SD_VARLINK_DEFINE_OUTPUT(filterDomains, SD_VARLINK_STRING, SD_VARLINK_NULLABLE|SD_VARLINK_ARRAY),
33 SD_VARLINK_FIELD_COMMENT("Require the specified number of labels or more in a domain for the hook to be considered."),
34 SD_VARLINK_DEFINE_OUTPUT(filterLabelsMin, SD_VARLINK_INT, SD_VARLINK_NULLABLE),
35 SD_VARLINK_FIELD_COMMENT("Require the specified number of labels or less in a domain for the hook to be considered."),
36 SD_VARLINK_DEFINE_OUTPUT(filterLabelsMax, SD_VARLINK_INT, SD_VARLINK_NULLABLE));
37
38 static SD_VARLINK_DEFINE_METHOD(
39 ResolveRecord,
40 SD_VARLINK_FIELD_COMMENT("The question being looked up, i.e. a combination of resource record keys. Note that unlike DNS "
41 "queries on the wire these lookups can carry multiple key requests, albeit closely related ones. "
42 "Specifically, lookups for A+AAAA for the the same hostname are submitted as one question, as "
43 "are lookups for TXT+SRV when doing DNS-SD resolution. Moreover, when looking up resources with "
44 "non-ASCII characters, they are placed together in a single question, once with labels encoded in "
45 "UTF-8, and once in IDNA. Hook implementations must be able to deal with these and other similar "
46 "combinations of resource key requests, and reply with all matching answers at once, or fail them "
47 "as one. Partial success/failure combinations are not supported."),
48 SD_VARLINK_DEFINE_INPUT_BY_TYPE(question, Question, SD_VARLINK_ARRAY),
49 SD_VARLINK_FIELD_COMMENT("A DNS response code. If a hook sets this return parameter further processing of the lookup via "
50 "regular protocols such as DNS, LLMNR, mDNS is skipped, and the return code returned immediately. "
51 "In other words, if a hook intends to let the request pass to normal resolution, it should not "
52 "set this return parameter."),
53 SD_VARLINK_DEFINE_OUTPUT(rcode, SD_VARLINK_INT, SD_VARLINK_NULLABLE),
54 SD_VARLINK_FIELD_COMMENT("An answer for a lookup, i.e. a combination of resource records, matching the request. This "
55 "should only be set when the 'rcode' parameter is returned as 0 (SUCCESS)."),
56 SD_VARLINK_DEFINE_OUTPUT_BY_TYPE(answer, Answer, SD_VARLINK_ARRAY|SD_VARLINK_NULLABLE));
57
58 SD_VARLINK_DEFINE_INTERFACE(
59 io_systemd_Resolve_Hook,
60 "io.systemd.Resolve.Hook",
61 SD_VARLINK_INTERFACE_COMMENT("Generic interface for implementing a domain name resolution hook."),
62 SD_VARLINK_SYMBOL_COMMENT("Encapsulates a positive lookup answer"),
63 &vl_type_Answer,
64 SD_VARLINK_SYMBOL_COMMENT("Encapsulates a lookup question"),
65 &vl_type_Question,
66 SD_VARLINK_SYMBOL_COMMENT("Encapsulates the class/type/name part of a DNS resource record."),
67 &vl_type_ResourceKey,
68 SD_VARLINK_SYMBOL_COMMENT("Encapsulates a DNS resource record."),
69 &vl_type_ResourceRecord,
70 SD_VARLINK_SYMBOL_COMMENT("Returns filter parameters for this hook. A hook service can implement this to reduce lookup "
71 "requests, by enabling itself only for certain domains or certain numbers of labels in the name. "
72 "It's recommended to implement this to reduce the number of redundant calls to each hook. Note "
73 "that this is advisory only, and implementing services must be able to gracefully handle lookup "
74 "requests that do not match this filter. This call is usually made with the 'more' flag set, in "
75 "which case the connection is left open after the first reply, and the implementing hook "
76 "services can send updates to the filter at any time. Whenever a further reply is sent the "
77 "filter configured therein fully replaces any previously communicated filter."),
78 &vl_method_QueryFilter,
79 SD_VARLINK_SYMBOL_COMMENT("Sent whenever a resolution request is made. This typically takes the filter parameters returned "
80 "by QueryFilter() into account, but this is not guaranteed."),
81 &vl_method_ResolveRecord);