| Copyright | (c) Viktor Dukhovni 2026 |
|---|---|
| License | BSD-3-Clause |
| Maintainer | ietf-dane@dukhovni.org |
| Stability | unstable |
| Safe Haskell | None |
| Language | GHC2024 |
Net.DNSBase.EDNS.Option
Description
The KnownEdnsOption typeclass binds a concrete option type to its
16-bit code; the existential EdnsOption wrapper lets an
option list hold a heterogeneous mix. Unknown option codes
decode as OpaqueOption from
Net.DNSBase.EDNS.Option.Opaque, preserving the raw bytes for
inspection or pass-through. Applications register new typed
options at runtime via registerEdnsOption;
options whose codec admits typed or value-driven extensions
(e.g. O_ede) also accept
extendEdnsOptionWithType /
extendEdnsOptionWithValue. See
Net.DNSBase.Extensible for the full guide.
The OptionCtl machinery, with optCtlSet / optCtlAdd, is
the building block QueryControls uses for per-call EDNS
option list tweaks — see EdnsOptionCtl.
Synopsis
- class (Typeable a, Eq a, Show a, Presentable a) => KnownEdnsOption a where
- type OptionExtensionVal a
- optionExtensionVal :: forall b -> b ~ a => OptionExtensionVal a
- optNum :: forall b -> b ~ a => OptNum
- optPres :: forall b -> b ~ a => Builder -> Builder
- optEncode :: forall s r. (Typeable r, Eq r, Show r) => a -> SPut s r
- optDecode :: forall b -> b ~ a => OptionExtensionVal b -> Int -> SGet EdnsOption
- data EdnsOption = KnownEdnsOption a => EdnsOption a
- fromOption :: KnownEdnsOption a => EdnsOption -> Maybe a
- monoOption :: (KnownEdnsOption a, Foldable t) => t EdnsOption -> [a]
- optionCode :: EdnsOption -> OptNum
- putOption :: forall s r. (Typeable r, Eq r, Show r) => EdnsOption -> SPut s r
- data OptionCodec
- data OptionCtl
- optCtlSet :: [EdnsOption] -> OptionCtl -> OptionCtl
- optCtlAdd :: [EdnsOption] -> OptionCtl -> OptionCtl
- emptyOptionCtl :: OptionCtl
- applyOptionCtl :: (OptionCtl -> OptionCtl) -> [EdnsOption] -> [EdnsOption]
Generic EDNS option class
class (Typeable a, Eq a, Show a, Presentable a) => KnownEdnsOption a where Source #
EDNS option class with conversion to/from opaque EdnsOption form.
Associated Types
type OptionExtensionVal a Source #
The codec-consumed extension value for option type a.
Defaults to (). Options with a non-trivial extension
(currently only O_ede, whose extension carries the
info-code name registry) supply their own associated-type
definition.
type OptionExtensionVal a = ()
Methods
optionExtensionVal :: forall b -> b ~ a => OptionExtensionVal a Source #
The library's built-in starting OptionExtensionVal for option
type a. Used as the baseline when the library installs
its built-in registration for a, and as the starting
point when the user extends the codec for a. For
OptionExtensionVal a ~ ()
default optionExtensionVal :: OptionExtensionVal a ~ () => forall b -> b ~ a => OptionExtensionVal a Source #
optNum :: forall b -> b ~ a => OptNum Source #
The EDNS option number
optPres :: forall b -> b ~ a => Builder -> Builder Source #
CPS option number presentation form builder. Most useful for new option values not yet known to the library.
Encoder of option data to wire form
Arguments
| :: forall b -> b ~ a | |
| => OptionExtensionVal b | Its extension value |
| -> Int | The encoded data length |
| -> SGet EdnsOption |
Decoder from wire form
Instances
data EdnsOption Source #
Existentially quantified type-opaque KnownEdnsOption, with heterogeneous
equality.
Constructors
| KnownEdnsOption a => EdnsOption a |
Instances
| Presentable EdnsOption Source # | |
Defined in Net.DNSBase.EDNS.Internal.Option Methods present :: EdnsOption -> Builder -> Builder Source # presentLazy :: EdnsOption -> ByteString -> ByteString Source # | |
| Show EdnsOption Source # | |
Defined in Net.DNSBase.EDNS.Internal.Option Methods showsPrec :: Int -> EdnsOption -> ShowS # show :: EdnsOption -> String # showList :: [EdnsOption] -> ShowS # | |
| Eq EdnsOption Source # | |
Defined in Net.DNSBase.EDNS.Internal.Option | |
fromOption :: KnownEdnsOption a => EdnsOption -> Maybe a Source #
Extract specific KnownEdnsOption from existential wrapping
monoOption :: (KnownEdnsOption a, Foldable t) => t EdnsOption -> [a] Source #
Filter a Foldable of EdnsOption down to the values of a
single type a, dropping any entries whose option-code does
not match (or whose value is held under an OpaqueOption even
though a is registered for that code). Use a type
application to select the target type, e.g. monoOption @O_ede
ednsOptions
optionCode :: EdnsOption -> OptNum Source #
The 16-bit OptNum codepoint of the option wrapped inside a
EdnsOption. Useful for filtering or grouping a heterogeneous
option list without unpacking each value.
putOption :: forall s r. (Typeable r, Eq r, Show r) => EdnsOption -> SPut s r Source #
Wire-form encoder for a EdnsOption: writes the 16-bit
option code followed by the length-prefixed value bytes
produced by the underlying optEncode method. Used by the
OPT pseudo-RR encoder to serialise each option in turn.
Extensibility
data OptionCodec Source #
Known EDNS option Proxy + OptionExtensionVal pair, paralleling
RDataCodec on the RR-type side.
Resolver EDNS option controls
The list of EDNS options carried in the OPT pseudo-RR of an
outgoing query. Callers do not build an OptionCtl directly;
they build an endomorphism OptionCtl -> OptionCtloptCtlAdd and optCtlSet and pass it to the EdnsOptionCtl
pattern of QueryControls. The endomorphism is applied to the
resolver's ambient option list at send time, so callers see the
final list as a delta on top of whatever the resolver already
had configured.
optCtlSet :: [EdnsOption] -> OptionCtl -> OptionCtl Source #
Replace the option list outright with the supplied options.
Use this when the per-call configuration should override
anything the resolver had set; combine with optCtlAdd for
partial overrides.
optCtlAdd :: [EdnsOption] -> OptionCtl -> OptionCtl Source #
Add the supplied options to the existing list. When the new
and old options share an OPTCODE, the new entries replace the
old ones with that code.
emptyOptionCtl :: OptionCtl Source #
The empty option list. Useful as the seed when running an
OptionCtl endomorphism to inspect what it would produce.
applyOptionCtl :: (OptionCtl -> OptionCtl) -> [EdnsOption] -> [EdnsOption] Source #
Apply an OptionCtl endomorphism to a plain list of options.
Used by the resolver to fold per-call EDNS-option tweaks into
the option list it is about to put on the wire.