add support for setting protocol handlers with {.raises.} annotation

All of the internal protocol handlers are restricted to `{.raises.}` of
`[CancelledError]`. However, the `LPProtoHandler` type is part of the
public interface, and example / test code raises more errors than just
`[CancelledError]`. The caller is aware of that and `CatchableError` is
caught.

To allow annotating the internal handlers with the proper `{.raises`.}
annotation, support for an extra `LPProtoHandler2` is added. This is
backward compatible as the old `LPProtoHandler` is still allowed.
Examples still compile fine. There is one test that needs a slight
adjustment as it accesses the internal `handler` field directly. That
field needs to be renamed so that the `template` is used instead.

Eventually, `LPProtoHandler` may be phased out, with appropriate notices
to users who define custom handlers and the migration requiring errors
to be handled inside the handler instead of raising them. At this time,
such a deprecation is not yet applied, especially while the internal
logic is still relying on the previous handler flow.

Author: etan-status

libp2p/multistream.nim

@@ -1,5 +1,5 @@
 # Nim-LibP2P
-# Copyright (c) 2023 Status Research & Development GmbH
+# Copyright (c) 2023-2024 Status Research & Development GmbH
 # Licensed under either of
 #  * Apache License, version 2.0, ([LICENSE-APACHE](LICENSE-APACHE))
 #  * MIT license ([LICENSE-MIT](LICENSE-MIT))
@@ -230,7 +230,7 @@ proc addHandler*(m: MultistreamSelect,
 
 proc addHandler*(m: MultistreamSelect,
                  codec: string,
-                 handler: LPProtoHandler,
+                 handler: LPProtoHandler|LPProtoHandler2,
                  matcher: Matcher = nil) =
   ## helper to allow registering pure handlers
   trace "registering proto handler", proto = codec

libp2p/protocols/protocol.nim

@@ -1,5 +1,5 @@
 # Nim-LibP2P
-# Copyright (c) 2023 Status Research & Development GmbH
+# Copyright (c) 2023-2024 Status Research & Development GmbH
 # Licensed under either of
 #  * Apache License, version 2.0, ([LICENSE-APACHE](LICENSE-APACHE))
 #  * MIT license ([LICENSE-MIT](LICENSE-MIT))
@@ -19,14 +19,16 @@ const
 
 type
   LPProtoHandler* = proc (
-    conn: Connection,
-    proto: string):
-    Future[void]
-    {.gcsafe, raises: [].}
+      conn: Connection,
+      proto: string): Future[void] {.async.}
+
+  LPProtoHandler2* = proc (
+      conn: Connection,
+      proto: string): Future[void] {.async: (raises: [CancelledError]).}
 
   LPProtocol* = ref object of RootObj
     codecs*: seq[string]
-    handler*: LPProtoHandler ## this handler gets invoked by the protocol negotiator
+    handlerImpl: LPProtoHandler  ## invoked by the protocol negotiator
     started*: bool
     maxIncomingStreams: Opt[int]
 
@@ -41,23 +43,47 @@ proc `maxIncomingStreams=`*(p: LPProtocol, val: int) =
   p.maxIncomingStreams = Opt.some(val)
 
 func codec*(p: LPProtocol): string =
-  assert(p.codecs.len > 0, "Codecs sequence was empty!")
+  doAssert(p.codecs.len > 0, "Codecs sequence was empty!")
   p.codecs[0]
 
 func `codec=`*(p: LPProtocol, codec: string) =
   # always insert as first codec
   # if we use this abstraction
   p.codecs.insert(codec, 0)
 
+template `handler`*(p: LPProtocol): LPProtoHandler =
+  p.handlerImpl
+
+template `handler`*(
+    p: LPProtocol, conn: Connection, proto: string): Future[void] =
+  p.handlerImpl(conn, proto)
+
+func `handler=`*(p: LPProtocol, handler: LPProtoHandler) =
+  p.handlerImpl = handler
+
+func `handler=`*(p: LPProtocol, handler: LPProtoHandler2) =
+  proc wrap(conn: Connection, proto: string): Future[void] {.async.} =
+    await handler(conn, proto)
+  p.handlerImpl = wrap
+
 proc new*(
-  T: type LPProtocol,
-  codecs: seq[string],
-  handler: LPProtoHandler,
-  maxIncomingStreams: Opt[int] | int = Opt.none(int)): T =
+    T: type LPProtocol,
+    codecs: seq[string],
+    handler: LPProtoHandler,
+    maxIncomingStreams: Opt[int] | int = Opt.none(int)): T =
   T(
     codecs: codecs,
-    handler: handler,
+    handlerImpl: handler,
     maxIncomingStreams:
       when maxIncomingStreams is int: Opt.some(maxIncomingStreams)
       else: maxIncomingStreams
   )
+
+proc new*(
+    T: type LPProtocol,
+    codecs: seq[string],
+    handler: LPProtoHandler2,
+    maxIncomingStreams: Opt[int] | int = Opt.none(int)): T =
+  proc wrap(conn: Connection, proto: string): Future[void] {.async.} =
+    await handler(conn, proto)
+  T.new(codec, wrap, maxIncomingStreams)

tests/testtortransport.nim

@@ -1,7 +1,7 @@
 {.used.}
 
 # Nim-Libp2p
-# Copyright (c) 2023 Status Research & Development GmbH
+# Copyright (c) 2023-2024 Status Research & Development GmbH
 # Licensed under either of
 #  * Apache License, version 2.0, ([LICENSE-APACHE](LICENSE-APACHE))
 #  * MIT license ([LICENSE-MIT](LICENSE-MIT))
@@ -88,7 +88,6 @@ suite "Tor transport":
 
       # every incoming connections will be in handled in this closure
       proc handle(conn: Connection, proto: string) {.async.} =
-
         var resp: array[6, byte]
         await conn.readExactly(addr resp, 6)
         check string.fromBytes(resp) == "client"
@@ -97,7 +96,7 @@ suite "Tor transport":
         # We must close the connections ourselves when we're done with it
         await conn.close()
 
-      return T(codecs: @[TestCodec], handler: handle)
+      return T.new(codecs = @[TestCodec], handler = handle)
 
     let rng = newRng()