mudfish_dns_module.h

下载 mudfish_dns_module.h，并将其放在与模块 C 源文件相同的目录中。下方是 Mudfish DNS 提供的完整头文件，包含兼容性声明。本指南中的模块请使用 C ABI v2 。

policy.c 示例 包含构建命令和 DNS 操作的示例。模块加载、钩子操作和缓冲区所有权规则请参考Native Module。

v2模块中使用的类型

型	用途
mudfish_dns_span	模块拥有的借用输入或替换响应的指针和长度。该字符串不以 NUL 结尾。
mudfish_dns_event	DNS 传输查询和响应数据、响应来源、原始目的地和现有域策略状态。
mudfish_dns_web_event	Web 数据、Host/SNI、目的地、协议、方向、现有域策略状态。 HTTPS 数据保持加密状态。
mudfish_dns_result	DNS 操作和可选回复地址、TTL 或替代回复。
mudfish_dns_module_v2	模块上下文、可选 DNS 和 Web 回调以及清理回调。

使用下面的签名向外界公开 mudfish_dns_module_init_v2()。主机以所有模块字段为 NULL 开始。在将值写入字段之前，请检查 ABI 版本和结构大小。将未使用的挂钩保留为 NULL，如果成功则返回 0。

如果初始化失败，请自行清理分配的资源。如果初始化成功，当模块不再使用时，主机会在卸载库之前调用 destroy() 一次。模块拥有的线程在此停止并等待终止。

完整标题

mudfish_dns_module.h

#ifndef MUDFISH_DNS_MODULE_H
#define MUDFISH_DNS_MODULE_H

#include <stddef.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

#define MUDFISH_DNS_MODULE_ABI_V1 1
#define MUDFISH_DNS_MODULE_ABI_V2 2
#define MUDFISH_DNS_CONTINUE 0
#define MUDFISH_DNS_REJECT 1
#define MUDFISH_DNS_BLOCK MUDFISH_DNS_REJECT
#define MUDFISH_DNS_ALLOW 2
#define MUDFISH_DNS_DROP 3
#define MUDFISH_DNS_ANSWER 4
#define MUDFISH_DNS_REPLACE 5

#define MUDFISH_DNS_IPV4 4
#define MUDFISH_DNS_IPV6 6

#define MUDFISH_DNS_SOURCE_QUERY 0
#define MUDFISH_DNS_SOURCE_UPSTREAM 1
#define MUDFISH_DNS_SOURCE_CACHE 2
#define MUDFISH_DNS_SOURCE_ORIGINAL 3
#define MUDFISH_DNS_SOURCE_ERROR 4
#define MUDFISH_DNS_SOURCE_MODULE 5

#define MUDFISH_DNS_WEB_UNKNOWN 0
#define MUDFISH_DNS_WEB_HTTP 1
#define MUDFISH_DNS_WEB_HTTPS 2
#define MUDFISH_DNS_TO_SERVER 1
#define MUDFISH_DNS_TO_CLIENT 2

/* Input spans are borrowed for this callback only; strings are not NUL terminated.
 * Empty spans have length zero and must not be dereferenced. Never mutate, free,
 * or retain any host pointer. DNS messages use wire format without TCP framing.
 */
struct mudfish_dns_span {
	const uint8_t *data;
	size_t len;
};

struct mudfish_dns_event {
	struct mudfish_dns_span query;
	struct mudfish_dns_span response; /* Empty in on_dns_query. */
	struct mudfish_dns_span original_destination; /* IP:port, empty for loopback. */
	uint32_t source;
	uint32_t applied; /* Existing domain policy selects protected resolution. */
};

struct mudfish_dns_web_event {
	struct mudfish_dns_span data;
	struct mudfish_dns_span hostname; /* Normalized Host/SNI, or empty. */
	struct mudfish_dns_span destination; /* IP:port. */
	uint32_t protocol;
	uint32_t direction;
	uint32_t applied; /* Existing domain policy selects web protection. */
};

/* Return CONTINUE or REJECT. Any other value fails the request/connection.
 * Hooks run in load order and stop at the first non-CONTINUE result.
 * Calls for one module instance are serialized, but may use different threads.
 * Hooks must finish promptly, must not unwind/longjmp across the ABI, and must
 * not call back into the host. HTTPS data is encrypted; no TLS termination.
 */
struct mudfish_dns_module_v1 {
	void *context;
	int32_t (*on_dns_query)(void *, const struct mudfish_dns_event *);
	int32_t (*on_dns_response)(void *, const struct mudfish_dns_event *);
	int32_t (*on_web_hello)(void *, const struct mudfish_dns_web_event *);
	int32_t (*on_web_data)(void *, const struct mudfish_dns_web_event *);
	void (*destroy)(void *);
};

/* Export this exact symbol. The host initializes all fields to NULL.
 * Check abi_version and module_size before writing. NULL hooks are optional.
 * The output pointer is valid only during init. Return zero on success.
 * On failure, clean up your own resources; the host will not call destroy.
 * On success, destroy runs once after all users finish, before dlclose. Any
 * module-owned threads must stop/join in destroy. Module code runs with the
 * service's privileges and must satisfy this contract, including constructors.
 */
int32_t mudfish_dns_module_init_v1(uint32_t abi_version, size_t module_size,
    struct mudfish_dns_module_v1 *module);

/* DNS v2 hooks return zero on success, nonzero on error (SERVFAIL).
 * The host zeroes result before each call. Set action to:
 * CONTINUE: consult the next module, then use the existing resolution/response.
 * ALLOW: stop this hook chain and use the existing resolution/response.
 * BLOCK: stop this hook chain and return REFUSED.
 * DROP: discard this query/response without sending any DNS response.
 * ANSWER: replace the response with the IP below, without upstream resolution
 *         when used in on_dns_query. IPv4 produces A, IPv6 produces AAAA.
 *         Other question types/classes get empty NOERROR (including an address
 *         family mismatch); IN/ANY gets the selected address record.
 * REPLACE: use result.response as the complete DNS wire response. Valid in
 *          either DNS hook. The ID, opcode and question must match the query.
 * Unknown actions or invalid ANSWER address families fail with SERVFAIL.
 * Query results except DROP still pass through the response hook chain.
 * Response decisions are final and never invoke response hooks recursively.
 * Synthetic/replaced responses are not stored in the host cache.
 * The host clears AD on replacements; modules must remove stale DNSSEC records
 * when modifying signed data. The host does not re-sign or validate DNSSEC.
 * DROP leaves TCP open for subsequent queries, subject to the normal timeout.
 * ALLOW does not change domain policy, upstream selection or transport checks.
 * All v1 lifetime/threading rules apply; result is writable only during the
 * callback and must not be retained. Web hooks retain v1 return semantics.
 */
struct mudfish_dns_result {
	uint32_t action;
	uint32_t ttl; /* ANSWER: seconds, zero is allowed. */
	uint32_t address_family; /* ANSWER: MUDFISH_DNS_IPV4 or MUDFISH_DNS_IPV6. */
	uint8_t address[16]; /* Network byte order; IPv4 uses the first 4 bytes. */
	/* REPLACE: module-owned wire response (12..65535 bytes, no TCP framing).
	 * Must remain valid and unchanged until the next callback on this instance
	 * or destroy; do not return stack memory or an event's borrowed pointer.
	 * The host copies before unlocking the instance and never frees this span.
	 */
	struct mudfish_dns_span response;
};

struct mudfish_dns_module_v2 {
	void *context;
	int32_t (*on_dns_query)(void *, const struct mudfish_dns_event *,
	    struct mudfish_dns_result *);
	int32_t (*on_dns_response)(void *, const struct mudfish_dns_event *,
	    struct mudfish_dns_result *);
	int32_t (*on_web_hello)(void *, const struct mudfish_dns_web_event *);
	int32_t (*on_web_data)(void *, const struct mudfish_dns_web_event *);
	void (*destroy)(void *);
};

/* Same initialization contract as v1, with ABI_V2 and sizeof(module_v2).
 * The host prefers v2 if exported, otherwise loads v1. A failed v2 init is fatal
 * and does not fall back to v1. Existing v1 modules need no changes.
 */
int32_t mudfish_dns_module_init_v2(uint32_t abi_version, size_t module_size,
    struct mudfish_dns_module_v2 *module);

#ifdef __cplusplus
}
#endif
#endif