nserver.middleware

AfterQueryHook module-attribute

AfterQueryHook = Callable[[Response], Response]

Type alias for HookMiddleware.after_query functions.

BeforeFirstQueryHook module-attribute

BeforeFirstQueryHook = Callable[[], None]

Type alias for HookMiddleware.before_first_query functions.

BeforeQueryHook module-attribute

BeforeQueryHook = Callable[[Query], RuleResult]

Type alias for HookMiddleware.before_query functions.

ExceptionHandler module-attribute

ExceptionHandler = Callable[[Query, Exception], Response]

Type alias for ExceptionHandlerMiddleware exception handler functions

QueryMiddlewareCallable module-attribute

QueryMiddlewareCallable = Callable[[Query], Response]

Type alias for functions that can be used with QueryMiddleware.next_function

RawRecordExceptionHandler module-attribute

RawRecordExceptionHandler = Callable[
    [dnslib.DNSRecord, Exception], dnslib.DNSRecord
]

Type alias for RawRecordExceptionHandlerMiddleware exception handler functions

RawRecordMiddlewareCallable module-attribute

RawRecordMiddlewareCallable = Callable[
    [dnslib.DNSRecord], dnslib.DNSRecord
]

Type alias for functions that can be used with RawRecordMiddleware.next_function

ExceptionHandlerMiddleware

ExceptionHandlerMiddleware(
    exception_handlers: Optional[
        Dict[Type[Exception], ExceptionHandler]
    ] = None
)

Bases: QueryMiddleware

Middleware for handling exceptions originating from a QueryMiddleware stack.

Allows registering handlers for individual Exception types. Only one handler can exist for a given Exception type.

When an exception is encountered, the middleware will search for the first handler that matches the class or parent class of the exception in method resolution order. If no handler is registered will use this classes self.default_exception_handler.

New in 2.0.

Attributes:

Name	Type	Description
exception_handlers		registered exception handlers

Parameters:

Name	Type	Description	Default
exception_handlers	Optional[Dict[Type[Exception], ExceptionHandler]]	exception handlers to assign	None

default_exception_handler staticmethod

default_exception_handler(
    query: Query, exception: Exception
) -> Response

The default exception handler

get_exception_handler

get_exception_handler(
    exception: Exception,
) -> ExceptionHandler

Get the exception handler for an Exception.

Parameters:

Name	Type	Description	Default
exception	Exception	the exception we wish to handle	required

process_query

process_query(
    query: Query, call_next: QueryMiddlewareCallable
) -> Response

Call the next function catching any handling any errors

register_next_function

register_next_function(
    next_function: QueryMiddlewareCallable,
) -> None

Set the next_function of this middleware

HookMiddleware

HookMiddleware(
    before_first_query: Optional[
        List[BeforeFirstQueryHook]
    ] = None,
    before_query: Optional[List[BeforeQueryHook]] = None,
    after_query: Optional[List[AfterQueryHook]] = None,
)

Bases: QueryMiddleware

Middleware for processing hook functions

There are three types of hooks:

before_first_query hooks will be run once at the time that the first query is received. They take no arguments and return no results. These are guaranteed to run at most once - however if any hook fails it will cause no other hooks to be run. Subsequent queries will continue to be processed regardless of if all before_first_query hooks ran or not.

before_query hooks will be run before each request. They receive a Query as an argument. If a hooks returns a non None result, process will skip to result processing.

after_query hooks will be run after a result has been returned from a before_query hook or from the next function in the middleware chain. They take a Response input and must return a Response.

New in 2.0.

Attributes:

Name	Type	Description
before_first_query	List[BeforeFirstQueryHook]	before_first_query hooks
before_query	List[BeforeQueryHook]	before_query hooks
after_query	List[AfterQueryHook]	after_query hooks
before_first_query_run	bool	have we run the before_first_query hooks
before_first_query_failed	bool	did any before_first_query hooks fail

Parameters:

Name	Type	Description	Default
before_first_query	Optional[List[BeforeFirstQueryHook]]	initial before_first_query hooks to register	None
before_query	Optional[List[BeforeQueryHook]]	initial before_query hooks to register	None
after_query	Optional[List[AfterQueryHook]]	initial after_query hooks to register	None

process_query

process_query(
    query: Query, call_next: QueryMiddlewareCallable
) -> Response

Process a query running relevant hooks.

register_next_function

register_next_function(
    next_function: QueryMiddlewareCallable,
) -> None

Set the next_function of this middleware

QueryMiddleware

QueryMiddleware()

Middleware for interacting with Query objects

New in 2.0.

process_query

process_query(
    query: Query, call_next: QueryMiddlewareCallable
) -> Response

Handle an incoming query.

Child classes should override this function (if they do not this middleware will simply pass the query onto the next function).

Parameters:

Name	Type	Description	Default
query	Query	the incoming query	required
call_next	QueryMiddlewareCallable	the next function in the chain	required

register_next_function

register_next_function(
    next_function: QueryMiddlewareCallable,
) -> None

Set the next_function of this middleware

QueryMiddlewareProcessor

QueryMiddlewareProcessor(
    query_middleware: QueryMiddlewareCallable,
)

Convert an incoming DNS record and pass it to a QueryMiddleware stack.

This class serves as the bottom of the RawRcordMiddleware stack.

New in 2.0.

Parameters:

Name	Type	Description	Default
query_middleware	QueryMiddlewareCallable	the top of the middleware stack	required

RawRecordExceptionHandlerMiddleware

RawRecordExceptionHandlerMiddleware(
    exception_handlers: Optional[
        Dict[Type[Exception], RawRecordExceptionHandler]
    ] = None
)

Bases: RawRecordMiddleware

Middleware for handling exceptions originating from a RawRecordMiddleware stack.

Allows registering handlers for individual Exception types. Only one handler can exist for a given Exception type.

When an exception is encountered, the middleware will search for the first handler that matches the class or parent class of the exception in method resolution order. If no handler is registered will use this classes self.default_exception_handler.

Important

Exception handlers are expected to be robust - that is, they must always return correctly even if they internally encounter an Exception.

New in 2.0.

Attributes:

Name	Type	Description
exception_handlers	Dict[Type[Exception], RawRecordExceptionHandler]	registered exception handlers

default_exception_handler staticmethod

default_exception_handler(
    record: dnslib.DNSRecord, exception: Exception
) -> dnslib.DNSRecord

Default exception handler

get_exception_handler

get_exception_handler(
    exception: Exception,
) -> RawRecordExceptionHandler

Get the exception handler for the given exception

Parameters:

Name	Type	Description	Default
exception	Exception	the exception we wish to handle	required

process_record

process_record(
    record: dnslib.DNSRecord,
    call_next: RawRecordMiddlewareCallable,
) -> dnslib.DNSRecord

Call the next function handling any exceptions that arise

register_next_function

register_next_function(
    next_function: RawRecordMiddlewareCallable,
) -> None

Set the next_function of this middleware

RawRecordMiddleware

RawRecordMiddleware()

Middleware to be run against raw dnslib.DNSRecords.

New in 2.0.

process_record

process_record(
    record: dnslib.DNSRecord,
    call_next: RawRecordMiddlewareCallable,
) -> dnslib.DNSRecord

Handle an incoming record.

Child classes should override this function (if they do not this middleware will simply pass the record onto the next function).

Parameters:

Name	Type	Description	Default
record	DNSRecord	the incoming record	required
call_next	RawRecordMiddlewareCallable	the next function in the chain	required

register_next_function

register_next_function(
    next_function: RawRecordMiddlewareCallable,
) -> None

Set the next_function of this middleware

RuleProcessor

RuleProcessor(rules: List[RuleBase])

Find and run a matching rule function.

This class serves as the bottom of the QueryMiddleware stack.

New in 2.0.

Parameters:

Name	Type	Description	Default
rules	List[RuleBase]	rules to run against	required

coerce_to_response

coerce_to_response(result: RuleResult) -> Response

Convert some RuleResult to a Response

New in 2.0.

Parameters:

Name	Type	Description	Default
result	RuleResult	the results to convert	required

Raises:

Type	Description
TypeError	unsupported result type