| Copyright | (c) Viktor Dukhovni 2026 |
|---|---|
| License | BSD-3-Clause |
| Maintainer | ietf-dane@dukhovni.org |
| Stability | unstable |
| Safe Haskell | None |
| Language | GHC2024 |
Net.DNSBase.RData.SVCB.SVCParamValue
Description
An SVCB or HTTPS record carries a list of (key, value) service
parameters. Each key has its own value type, so the value side is
structured as an extensible typeclass KnownSVCParamValue with
one instance per standardised key, wrapped in an existential
SVCParamValue so a single list can hold a heterogeneous mix.
Unknown keys fall through to OpaqueSPV, which preserves the raw
wire bytes for later inspection or pass-through.
Applications can add a new service-parameter type at runtime by
writing a KnownSVCParamValue instance and installing it via
extendRRwithType on the SVCB or HTTPS
RR type — see Net.DNSBase.Extensible for a worked example.
Synopsis
- class (Typeable a, Eq a, Ord a, Show a, Presentable a) => KnownSVCParamValue a where
- spvKey :: forall b -> b ~ a => SVCParamKey
- spvKeyPres :: forall b -> b ~ a => Builder -> Builder
- encodeSPV :: ErrorContext r => a -> SPut s r
- decodeSPV :: forall b -> b ~ a => Int -> SGet SVCParamValue
- data SVCParamValue = KnownSVCParamValue a => SVCParamValue a
- fromSPV :: KnownSVCParamValue a => SVCParamValue -> Maybe a
- serviceParamKey :: SVCParamValue -> SVCParamKey
- data OpaqueSPV (n :: Nat) where
- OpaqueSPV :: forall (n :: Nat). Nat16 n => ShortByteString -> OpaqueSPV n
- opaqueSPV :: Word16 -> ShortByteString -> SVCParamValue
- toOpaqueSPV :: SVCParamValue -> Either (EncodeErr (Maybe ())) SVCParamValue
Documentation
class (Typeable a, Eq a, Ord a, Show a, Presentable a) => KnownSVCParamValue a where Source #
The class of types representing the value side of a service
parameter inside an SVCB or HTTPS record. Each instance
corresponds to a specific SVCParamKey; the encodeSPV and
decodeSPV methods handle only the value bytes.
The Presentable instance builds the RFC 9460 zone-file
presentation form: the key name followed (where the value is
non-empty) by = and the value. The Show instance is
typically derived and aims to produce syntactically valid
Haskell.
Methods
spvKey :: forall b -> b ~ a => SVCParamKey Source #
The associated key number
spvKeyPres :: forall b -> b ~ a => Builder -> Builder Source #
CPS presentation form builder for the key
encodeSPV :: ErrorContext r => a -> SPut s r Source #
Encode value to wire form.
The surrounding (key, length) frame is owned by the
SVCB-record encoder: encodeSPV writes just the payload,
and the framework wraps the result in the 2-byte length
prefix. For valueless parameters this means encodeSPV
is just pure ().
decodeSPV :: forall b -> b ~ a => Int -> SGet SVCParamValue Source #
Decode value from wire form. The overall SVCB RData decoder gives each parameter decoder a view into a buffer of exactly the indicated length, and makes sure exactly that many bytes are consumed. The length argument is only needed in decoders that read variable-length fields that run to the end of the record.
Instances
data SVCParamValue Source #
Existential wrapper around any KnownSVCParamValue, so a
single list can hold a mix of typed service parameters. The
present method delegates to the underlying instance, which
emits both the key name and the value.
Constructors
| KnownSVCParamValue a => SVCParamValue a |
Instances
fromSPV :: KnownSVCParamValue a => SVCParamValue -> Maybe a Source #
Extract specific known SVCParamValue from existential wrapping
serviceParamKey :: SVCParamValue -> SVCParamKey Source #
Key associated with a generic SvcParamValue
data OpaqueSPV (n :: Nat) where Source #
Fallback carrier for service-parameter values whose key code
has no KnownSVCParamValue instance registered. The key code
is encoded as a type-level natural so OpaqueSPV values with
different codes have distinct types. The wire payload is kept
as raw bytes and round-trips losslessly; the presentation form
is keyN=... with the value as a DnsText character-string.
Constructors
| OpaqueSPV :: forall (n :: Nat). Nat16 n => ShortByteString -> OpaqueSPV n |
Instances
| Nat16 n => Presentable (OpaqueSPV n) Source # | |
Defined in Net.DNSBase.RData.SVCB.SVCParamValue Methods present :: OpaqueSPV n -> Builder -> Builder Source # presentLazy :: OpaqueSPV n -> ByteString -> ByteString Source # | |
| Nat16 n => KnownSVCParamValue (OpaqueSPV n) Source # | |
Defined in Net.DNSBase.RData.SVCB.SVCParamValue | |
| Show (OpaqueSPV n) Source # | |
| Eq (OpaqueSPV n) Source # | |
| Ord (OpaqueSPV n) Source # | |
Defined in Net.DNSBase.RData.SVCB.SVCParamValue | |
opaqueSPV :: Word16 -> ShortByteString -> SVCParamValue Source #
Build an SVCParamValue from a raw numeric key and a raw
byte payload. Useful when a caller has a wire encoding for a
key that has no registered KnownSVCParamValue instance, or
when round-tripping bytes for keys that should remain
uninterpreted.
toOpaqueSPV :: SVCParamValue -> Either (EncodeErr (Maybe ())) SVCParamValue Source #
Encode an SVCParamValue to its OpaqueSPV equivalent under
the same key code. Values that are already opaque are returned
unchanged. For typed values this re-encodes the payload to
wire form; encoding can fail (for example if the result would
be too long to fit a 16-bit length field), in which case the
EncodeErr is returned.