Implemented submarine error propagation for Handle

.scalafmt.conf

@@ -50,3 +50,9 @@ rewriteTokens {
   "→": "->"
   "←": "<-"
 }
+
+fileOverride {
+  "glob:**/scala-3/cats/mtl/**" {
+    runner.dialect = scala3
+  }
+}

core/src/main/scala-2/cats/mtl/HandleVariant.scala

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2021 Typelevel
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package cats
+package mtl
+
+trait HandleVariant

core/src/main/scala-3/cats/mtl/HandleVariant.scala

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2021 Typelevel
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package cats
+package mtl
+
+trait HandleVariant { this: Handle.type =>
+  import Handle.Submarine
+
+  def allow[E]: AdHocSyntaxWired[E] =
+    new AdHocSyntaxWired[E]
+
+  final class AdHocSyntaxWired[E]:
+
+    def apply[F[_], A](body: Handle[F, E] ?=> F[A])(using ApplicativeThrow[F]): Inner[F, A] =
+      new Inner(body)
+
+    final class Inner[F[_], A](body: Handle[F, E] ?=> F[A])(using ApplicativeThrow[F]):
+      def rescue(h: E => F[A]): F[A] =
+        val Marker = new AnyRef
+
+        def inner[B](fb: F[B])(f: E => F[B]): F[B] =
+          ApplicativeThrow[F].handleErrorWith(fb):
+            case Submarine(e, Marker) => f(e.asInstanceOf[E])
+            case t => ApplicativeThrow[F].raiseError(t)
+
+        given Handle[F, E] with
+          def applicative = Applicative[F]
+          def raise[E2 <: E, B](e: E2): F[B] =
+            ApplicativeThrow[F].raiseError(Submarine(e, Marker))
+          def handleWith[B](fb: F[B])(f: E => F[B]): F[B] = inner(fb)(f)
+
+        inner(body)(h)
+}

core/src/main/scala/cats/mtl/Handle.scala

@@ -20,6 +20,7 @@ package mtl
 import cats.data._
 
 import scala.annotation.implicitNotFound
+import scala.util.control.NoStackTrace
 
 @implicitNotFound(
   "Could not find an implicit instance of Handle[${F}, ${E}]. If you\nhave a good way of handling errors of type ${E} at this location, you may want\nto construct a value of type EitherT for this call-site, rather than ${F}.\nAn example type:\n\n  EitherT[${F}, ${E}, *]\n\nThis is analogous to writing try/catch around this call. The EitherT will\n\"catch\" the errors of type ${E}.\n\nIf you do not wish to handle errors of type ${E} at this location, you should\nadd an implicit parameter of this type to your function. For example:\n\n  (implicit fhandle: Handle[${F}, ${E}}])\n")
@@ -217,6 +218,41 @@ private[mtl] trait HandleInstances extends HandleLowPriorityInstances {
     }
 }
 
-object Handle extends HandleInstances {
+object Handle extends HandleInstances with HandleVariant {
+
   def apply[F[_], E](implicit ev: Handle[F, E]): Handle[F, E] = ev
+
+  def allowF[F[_], E]: AdHocSyntaxTired[F, E] =
+    new AdHocSyntaxTired[F, E]
+
+  final class AdHocSyntaxTired[F[_], E] {
+
+    def apply[A](body: Handle[F, E] => F[A])(implicit F: ApplicativeThrow[F]): Inner[A] =
+      new Inner(body)
+
+    final class Inner[A](body: Handle[F, E] => F[A])(implicit F: ApplicativeThrow[F]) {
+      def rescue(h: E => F[A]): F[A] = {
+        val Marker = new AnyRef
+
+        def inner[B](fb: F[B])(f: E => F[B]): F[B] =
+          ApplicativeThrow[F].handleErrorWith(fb) {
+            case Submarine(e, Marker) => f(e.asInstanceOf[E])
+            case t => ApplicativeThrow[F].raiseError(t)
+          }
+
+        val fa = body(new Handle[F, E] {
+          def applicative = Applicative[F]
+          def raise[E2 <: E, B](e: E2): F[B] =
+            ApplicativeThrow[F].raiseError(Submarine(e, Marker))
+          def handleWith[B](fb: F[B])(f: E => F[B]): F[B] = inner(fb)(f)
+        })
+
+        inner(fa)(h)
+      }
+    }
+  }
+
+  private[mtl] final case class Submarine[E](e: E, marker: AnyRef)
+      extends RuntimeException
+      with NoStackTrace
 }

tests/shared/src/test/scala-3/cats/mtl/tests/Handle3Tests.scala

@@ -0,0 +1,59 @@
+/*
+ * Copyright 2021 Typelevel
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package cats
+package mtl
+package tests
+
+import cats.data.EitherT
+import cats.mtl.syntax.all.*
+import cats.syntax.all.*
+import cats.mtl.Handle.*
+
+class Handle3Tests extends BaseSuite:
+
+  type F[A] = EitherT[Eval, Throwable, A]
+
+  test("submerge custom errors (scala 3)"):
+    enum Error:
+      case First, Second, Third
+
+    val test =
+      allow[Error]:
+        Error.Second.raise[F, String].as("nope")
+      .rescue:
+        case Error.First => "0".pure[F]
+        case Error.Second => "1".pure[F]
+        case Error.Third => "2".pure[F]
+
+    assert(test.value.value.toOption == Some("1"))
+
+  test("submerge two independent errors (scala 3)"):
+    enum Error1:
+      case First, Second, Third
+    enum Error2:
+      case Fourth
+    val test =
+      allow[Error1]:
+        allow[Error2]:
+          Error1.Third.raise[F, String].as("nope")
+        .rescue:
+          case e => e.toString.pure[F]
+      .rescue:
+        case Error1.First => "first1".pure[F]
+        case Error1.Second => "second1".pure[F]
+        case Error1.Third => "third1".pure[F]
+    assert(test.value.value.toOption == Some("third1"))

tests/shared/src/test/scala/cats/mtl/tests/HandleTests.scala

@@ -18,9 +18,16 @@ package cats
 package mtl
 package tests
 
-import cats.data.{Kleisli, WriterT}
+import cats.data.{EitherT, Kleisli, WriterT}
+import cats.laws.discipline.arbitrary._
+import cats.mtl.syntax.all._
+import cats.syntax.all._
+
+import org.scalacheck.{Arbitrary, Cogen}, Arbitrary.arbitrary
 
 class HandleTests extends BaseSuite {
+  type F[A] = EitherT[Eval, Throwable, A]
+
   test("handleForApplicativeError") {
     case class Foo[A](bar: A)
 
@@ -39,4 +46,80 @@ class HandleTests extends BaseSuite {
     Handle[Kleisli[Foo, Unit, *], String]
     Handle[WriterT[Foo, String, *], String]
   }
+
+  test("submerge custom errors") {
+    sealed trait Error extends Product with Serializable
+
+    object Error {
+      case object First extends Error
+      case object Second extends Error
+      case object Third extends Error
+    }
+
+    val test =
+      Handle.allowF[F, Error](implicit h => Error.Second.raise.as("nope")) rescue {
+        case Error.First => "0".pure[F]
+        case Error.Second => "1".pure[F]
+        case Error.Third => "2".pure[F]
+      }
+
+    assert(test.value.value.toOption == Some("1"))
+  }
+
+  test("submerge two independent errors") {
+    sealed trait Error1 extends Product with Serializable
+
+    object Error1 {
+      case object First extends Error1
+      case object Second extends Error1
+      case object Third extends Error1
+    }
+
+    sealed trait Error2 extends Product with Serializable
+
+    val test = Handle.allowF[F, Error1] { implicit h1 =>
+      Handle.allowF[F, Error2] { implicit h2 =>
+        val _ =
+          h2 // it's helpful to test the raise syntax infers even when multiple handles are present
+        Error1.Third.raise.as("nope")
+      } rescue { e => e.toString.pure[F] }
+    } rescue {
+      case Error1.First => "first1".pure[F]
+      case Error1.Second => "second1".pure[F]
+      case Error1.Third => "third1".pure[F]
+    }
+
+    assert(test.value.value.toOption == Some("third1"))
+  }
+
+  {
+    final case class Error(value: Int)
+
+    object Error {
+      implicit val arbError: Arbitrary[Error] =
+        Arbitrary(arbitrary[Int].flatMap(Error(_)))
+
+      implicit val cogenError: Cogen[Error] =
+        Cogen((_: Error).value.toLong)
+
+      implicit val eqError: Eq[Error] =
+        Eq.by((_: Error).value)
+    }
+
+    implicit val eqThrowable: Eq[Throwable] =
+      Eq.fromUniversalEquals[Throwable]
+
+    val test = Handle.allowF[F, Error] { implicit h =>
+      EitherT liftF {
+        Eval later {
+          checkAll(
+            "Handle.allowF[F, Error]",
+            cats.mtl.laws.discipline.HandleTests[F, Error].handle[Int])
+        }
+      }
+    } rescue { case Error(_) => ().pure[F] }
+
+    test.value.value
+    ()
+  }
 }