Integrate DTLS (pion/dtls) configuration using options instead of deprecated *dtls.Config{} (#645)

* chore: update Go version and pion/dtls in go.mod and go.sum

* feat: introduce options-based DTLS API and deprecate legacy methods

* feat: refactor DTLS API to use generic options-based configuration and deprecate legacy methods

* feat: update DTLS implementation to use options-based configuration across examples

* test: enhance error assertion in TestTLSListenerCheckForInfinitLoop for macOS compatibility

* docs: update README to reflect deprecation of *dtls.Config and introduce options-based DTLS API

* fix: ensure DTLS connection is closed on error in Dial function

* feat: update README and add example client for options-based DTLS API

* fix: clean up main function in DTLS client example

* fix: update indirect dependencies to latest versions

Author: sandrolain

README.md

@@ -80,8 +80,12 @@ The go-coap provides servers and clients for DTLS, TCP-TLS, UDP, TCP in golang l
         // for tcp-tls
         // log.Fatal(coap.ListenAndServeTLS("tcp", ":5688", &tls.Config{...}, r))
 
-        // for udp-dtls
+        // for udp-dtls (deprecated: *dtls.Config is deprecated in pion/dtls v3, prefer options-based API)
         // log.Fatal(coap.ListenAndServeDTLS("udp", ":5688", &dtls.Config{...}, r))
+
+        // for udp-dtls (options-based API — pion/dtls v3)
+        // log.Fatal(coap.ListenAndServeDTLS("udp", ":5688",
+        //     net.NewDTLSServerOptions(dtls.WithPSK(...), dtls.WithCertificates(...)), r))
     }
 ```
 
@@ -99,8 +103,12 @@ The go-coap provides servers and clients for DTLS, TCP-TLS, UDP, TCP in golang l
         // for tcp-tls
         // co, err := tcp.Dial("localhost:5688", tcp.WithTLS(&tls.Config{...}))
 
-        // for dtls
-        // co, err := dtls.Dial("localhost:5688", &dtls.Config{...}))
+        // for dtls (deprecated: *dtls.Config is deprecated in pion/dtls v3, prefer options-based API)
+        // co, err := dtls.Dial("localhost:5688", &dtls.Config{...})
+
+        // for dtls (options-based API — pion/dtls v3)
+        // co, err := dtls.Dial("localhost:5688",
+        //     dtlscoap.NewDTLSClientOptions(piondtls.WithPSK(...), piondtls.WithCertificates(...)))
 
         if err != nil {
             log.Fatalf("Error dialing: %v", err)
@@ -116,6 +124,43 @@ The go-coap provides servers and clients for DTLS, TCP-TLS, UDP, TCP in golang l
     }
 ```
 
+### DTLS Options-based API (pion/dtls v3)
+
+> **Deprecation notice:** `*dtls.Config` is [deprecated in pion/dtls v3](https://github.com/pion/dtls) in favour of immutable options-based configurations. Its use in go-coap is consequently deprecated as well and may be removed in a future major version. Migrate to `net.NewDTLSServerOptions` / `dtls.NewDTLSClientOptions` as shown below.
+
+In addition to the legacy `*dtls.Config`, go-coap supports the **options-based API** introduced in pion/dtls v3. Both approaches are currently accepted by the same generic functions (`ListenAndServeDTLS`, `Dial`, `NewDTLSListener`).
+
+Use `net.NewDTLSServerOptions(...)` / `dtls.NewDTLSClientOptions(...)` to compose DTLS configurations from individual options:
+
+```go
+import (
+    coap   "github.com/plgd-dev/go-coap/v3"
+    coapnet "github.com/plgd-dev/go-coap/v3/net"
+    coapdtls "github.com/plgd-dev/go-coap/v3/dtls"
+    piondtls "github.com/pion/dtls/v3"
+)
+
+// Server
+serverOpts := coapnet.NewDTLSServerOptions(
+    piondtls.WithPSK(func(hint []byte) ([]byte, error) {
+        return []byte{0xAB, 0xC1, 0x23}, nil
+    }),
+    piondtls.WithCipherSuites(piondtls.TLS_PSK_WITH_AES_128_CCM_8),
+)
+log.Fatal(coap.ListenAndServeDTLS("udp", ":5688", serverOpts, r))
+
+// Client
+clientOpts := coapdtls.NewDTLSClientOptions(
+    piondtls.WithPSK(func(hint []byte) ([]byte, error) {
+        return []byte{0xAB, 0xC1, 0x23}, nil
+    }),
+    piondtls.WithCipherSuites(piondtls.TLS_PSK_WITH_AES_128_CCM_8),
+)
+co, err := coapdtls.Dial("localhost:5688", clientOpts)
+```
+
+See [examples/options/server/](examples/options/server/) and [examples/options/client/](examples/options/client/) for complete working examples using the options-based API.
+
 ### Observe / Notify
 
 [Server](examples/observe/server/main.go) example.

dtls/client.go

@@ -33,19 +33,30 @@ var DefaultConfig = func() udpClient.Config {
 }()
 
 // Dial creates a client connection to the given target.
-func Dial(target string, dtlsCfg *dtls.Config, opts ...udp.Option) (*udpClient.Conn, error) {
-	cfg := DefaultConfig
+// cfg accepts either a *dtls.Config (backward-compatible legacy path) or a
+// DTLSClientOptions value built with NewDTLSClientOptions (recommended).
+func Dial[T DTLSClientConfig](target string, cfg T, opts ...udp.Option) (*udpClient.Conn, error) {
+	defaultCfg := DefaultConfig
 	for _, o := range opts {
-		o.UDPClientApply(&cfg)
+		o.UDPClientApply(&defaultCfg)
 	}
 
-	c, err := cfg.Dialer.DialContext(cfg.Ctx, cfg.Net, target)
+	c, err := defaultCfg.Dialer.DialContext(defaultCfg.Ctx, defaultCfg.Net, target)
 	if err != nil {
 		return nil, err
 	}
 
-	conn, err := dtls.Client(dtlsnet.PacketConnFromConn(c), c.RemoteAddr(), dtlsCfg)
+	var conn *dtls.Conn
+	switch v := any(cfg).(type) {
+	case *dtls.Config:
+		conn, err = dtls.Client(dtlsnet.PacketConnFromConn(c), c.RemoteAddr(), v) //nolint:staticcheck
+	case DTLSClientOptions:
+		conn, err = dtls.ClientWithOptions(dtlsnet.PacketConnFromConn(c), c.RemoteAddr(), v.opts...)
+	default:
+		panic("unreachable: unexpected type in DTLSClientConfig constraint")
+	}
 	if err != nil {
+		_ = c.Close()
 		return nil, err
 	}
 	opts = append(opts, options.WithCloseSocket())

dtls/client_test.go

@@ -797,3 +797,142 @@ func TestClientKeepAliveMonitor(t *testing.T) {
 	require.NoError(t, err)
 	require.True(t, inactivityDetected.Load())
 }
+
+// TestConnGetWithOptions mirrors TestConnGet but uses the new
+// generic Dial / NewDTLSListener API with DTLSClientOptions / DTLSServerOptions.
+func TestConnGetWithOptions(t *testing.T) {
+	type args struct {
+		path string
+		opts message.Options
+	}
+	tests := []struct {
+		name              string
+		args              args
+		wantCode          codes.Code
+		wantContentFormat *message.MediaType
+		wantPayload       interface{}
+		wantErr           bool
+	}{
+		{
+			name:              "ok-a",
+			args:              args{path: "/a"},
+			wantCode:          codes.BadRequest,
+			wantContentFormat: &message.TextPlain,
+			wantPayload:       make([]byte, 5330),
+		},
+		{
+			name:              "ok-b",
+			args:              args{path: "/b"},
+			wantCode:          codes.Content,
+			wantContentFormat: &message.TextPlain,
+			wantPayload:       []byte("b"),
+		},
+		{
+			name:     "notfound",
+			args:     args{path: "/c"},
+			wantCode: codes.NotFound,
+		},
+	}
+
+	pskCallback := func(hint []byte) ([]byte, error) {
+		fmt.Printf("Hint: %s \n", hint)
+		return []byte{0xAB, 0xC1, 0x23}, nil
+	}
+	serverOpts := coapNet.NewDTLSServerOptions(
+		piondtls.WithPSK(pskCallback),
+		piondtls.WithPSKIdentityHint([]byte("Pion DTLS Server")),
+		piondtls.WithCipherSuites(piondtls.TLS_PSK_WITH_AES_128_CCM_8),
+	)
+	clientOpts := dtls.NewDTLSClientOptions(
+		piondtls.WithPSK(pskCallback),
+		piondtls.WithPSKIdentityHint([]byte("Pion DTLS Server")),
+		piondtls.WithCipherSuites(piondtls.TLS_PSK_WITH_AES_128_CCM_8),
+	)
+
+	l, err := coapNet.NewDTLSListener("udp", "", serverOpts)
+	require.NoError(t, err)
+	defer func() {
+		errC := l.Close()
+		require.NoError(t, errC)
+	}()
+
+	var wg sync.WaitGroup
+	defer wg.Wait()
+
+	m := mux.NewRouter()
+	err = m.Handle("/a", mux.HandlerFunc(func(w mux.ResponseWriter, r *mux.Message) {
+		assert.Equal(t, codes.GET, r.Code())
+		errS := w.SetResponse(codes.BadRequest, message.TextPlain, bytes.NewReader(make([]byte, 5330)))
+		require.NoError(t, errS)
+		require.NotEmpty(t, w.Conn())
+	}))
+	require.NoError(t, err)
+	err = m.Handle("/b", mux.HandlerFunc(func(w mux.ResponseWriter, r *mux.Message) {
+		assert.Equal(t, codes.GET, r.Code())
+		errS := w.SetResponse(codes.Content, message.TextPlain, bytes.NewReader([]byte("b")))
+		require.NoError(t, errS)
+		require.NotEmpty(t, w.Conn())
+	}))
+	require.NoError(t, err)
+
+	s := dtls.NewServer(options.WithMux(m))
+	defer s.Stop()
+
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		errS := s.Serve(l)
+		assert.NoError(t, errS)
+	}()
+
+	cc, err := dtls.Dial(l.Addr().String(), clientOpts)
+	require.NoError(t, err)
+	defer func() {
+		errC := cc.Close()
+		require.NoError(t, errC)
+	}()
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			ctx, cancel := context.WithTimeout(context.Background(), Timeout)
+			defer cancel()
+			got, err := cc.Get(ctx, tt.args.path, tt.args.opts...)
+			if tt.wantErr {
+				require.Error(t, err)
+				return
+			}
+			require.NoError(t, err)
+			require.Equal(t, tt.wantCode, got.Code())
+			if tt.wantContentFormat != nil {
+				ct, err := got.ContentFormat()
+				require.NoError(t, err)
+				require.Equal(t, *tt.wantContentFormat, ct)
+				buf := bytes.NewBuffer(nil)
+				_, err = buf.ReadFrom(got.Body())
+				require.NoError(t, err)
+				require.Equal(t, tt.wantPayload, buf.Bytes())
+			}
+		})
+	}
+}
+
+// TestNewDTLSListenerInvalidAddr verifies that
+// NewDTLSListener propagates address-resolution errors.
+func TestNewDTLSListenerInvalidAddr(t *testing.T) {
+	_, err := coapNet.NewDTLSListener("udp", "!!invalid!!", coapNet.NewDTLSServerOptions(
+		piondtls.WithPSK(func([]byte) ([]byte, error) { return []byte{0x01}, nil }),
+		piondtls.WithCipherSuites(piondtls.TLS_PSK_WITH_AES_128_CCM_8),
+	))
+	require.Error(t, err)
+}
+
+// TestDialConnectRefused ensures Dial returns an error
+// when nothing is listening on the target address.
+func TestDialConnectRefused(t *testing.T) {
+	// port 1 is reserved and will never have a DTLS listener
+	_, err := dtls.Dial("127.0.0.1:1", dtls.NewDTLSClientOptions(
+		piondtls.WithPSK(func([]byte) ([]byte, error) { return []byte{0x01}, nil }),
+		piondtls.WithCipherSuites(piondtls.TLS_PSK_WITH_AES_128_CCM_8),
+	))
+	require.Error(t, err)
+}

dtls/clientoptions.go

@@ -0,0 +1,28 @@
+package dtls
+
+import piondtls "github.com/pion/dtls/v3"
+
+// DTLSClientOptions holds DTLS client-side configuration options for use with
+// Dial. It wraps the options-based API of pion/dtls, keeping
+// pion/dtls option types out of go-coap function signatures.
+type DTLSClientOptions struct {
+	opts []piondtls.ClientOption
+}
+
+// NewDTLSClientOptions creates a DTLSClientOptions from the provided pion/dtls
+// ClientOption values (e.g. piondtls.WithPSK, piondtls.WithCertificates, …).
+//
+// Most pion/dtls options implement the shared piondtls.Option interface, which
+// satisfies both ServerOption and ClientOption, so they can be passed here
+// directly.
+func NewDTLSClientOptions(opts ...piondtls.ClientOption) DTLSClientOptions {
+	return DTLSClientOptions{opts: opts}
+}
+
+// DTLSClientConfig is a type constraint accepted by Dial.
+// It allows callers to pass either the legacy *piondtls.Config
+// (backward-compatible) or the recommended DTLSClientOptions wrapper
+// (built via NewDTLSClientOptions).
+type DTLSClientConfig interface {
+	*piondtls.Config | DTLSClientOptions
+}

dtls/example_test.go

@@ -39,6 +39,32 @@ func ExampleConn_Get() {
 	fmt.Printf("%v", data)
 }
 
+func ExampleDial_withOptions() {
+	conn, err := dtls.Dial("pluggedin.cloud:5684", dtls.NewDTLSClientOptions(
+		piondtls.WithPSK(func(hint []byte) ([]byte, error) {
+			fmt.Printf("Hint: %s \n", hint)
+			return []byte{0xAB, 0xC1, 0x23}, nil
+		}),
+		piondtls.WithPSKIdentityHint([]byte("Pion DTLS Server")),
+		piondtls.WithCipherSuites(piondtls.TLS_PSK_WITH_AES_128_CCM_8),
+	))
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer conn.Close()
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+	defer cancel()
+	res, err := conn.Get(ctx, "/oic/res")
+	if err != nil {
+		log.Fatal(err)
+	}
+	data, err := io.ReadAll(res.Body())
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Printf("%v", data)
+}
+
 func ExampleServer() {
 	dtlsCfg := &piondtls.Config{
 		PSK: func(hint []byte) ([]byte, error) {
@@ -57,3 +83,21 @@ func ExampleServer() {
 	defer s.Stop()
 	log.Fatal(s.Serve(l))
 }
+
+func ExampleNewDTLSListener_withOptions() {
+	l, err := net.NewDTLSListener("udp", "0.0.0.0:5683", net.NewDTLSServerOptions(
+		piondtls.WithPSK(func(hint []byte) ([]byte, error) {
+			fmt.Printf("Hint: %s \n", hint)
+			return []byte{0xAB, 0xC1, 0x23}, nil
+		}),
+		piondtls.WithPSKIdentityHint([]byte("Pion DTLS Server")),
+		piondtls.WithCipherSuites(piondtls.TLS_PSK_WITH_AES_128_CCM_8),
+	))
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer l.Close()
+	s := dtls.NewServer()
+	defer s.Stop()
+	log.Fatal(s.Serve(l))
+}