feat(core): improve error handling and type safety

- Add type alias HttpErrorResponse for (StatusCode, PillarsError.View)
- Add extension method toEitherWithError for Option to Either conversion

Author: rlemaitre

.g8/module/modules/$moduleFolder$/src/main/scala/pillars/$package$/$Prefix$Loader.scala

@@ -15,7 +15,8 @@ import io.github.iltotore.iron.*
 import io.github.iltotore.iron.circe.given
 import io.github.iltotore.iron.constraint.all.*
 import org.typelevel.otel4s.trace.Tracer
-import pillars.Config.Secret
+import pillars.Config
+import pillars.Config.*
 import pillars.Module
 import pillars.ModuleDef
 import pillars.Modules
@@ -75,10 +76,10 @@ case class $Prefix$Config(
     port: Port = port"5672",
     username: Option[$Prefix$User] = None,
     password: Option[Secret[$Prefix$Password]] = None
-)
+) extends Config
 
 object $Prefix$Config:
-    given Configuration         = Configuration.default.withKebabCaseMemberNames.withKebabCaseConstructorNames.withDefaults
+    given Configuration         = defaultCirceConfig
     given Codec[$Prefix$Config] = Codec.AsObject.derivedConfigured
 end $Prefix$Config
 

modules/core/src/main/scala/pillars/AdminServer.scala

@@ -11,42 +11,27 @@ import com.comcast.ip4s.*
 import io.circe.Codec
 import io.circe.derivation.Configuration
 import pillars.AdminServer.Config
-import sttp.model.StatusCode
+import scribe.cats.io.*
 import sttp.tapir.*
 
-final case class AdminServer(
-    config: Config,
-    infos: AppInfo,
-    obs: Observability,
-    controllers: List[Controller]
-):
+final case class AdminServer(config: Config, infos: AppInfo, obs: Observability, controllers: List[Controller]):
     def start(): IO[Unit] =
-        val logger = scribe.cats.io
-        import logger.*
-        if config.enabled then
+        IO.whenA(config.enabled):
             for
                 _ <- info(s"Starting admin server on ${config.http.host}:${config.http.port}")
                 _ <- HttpServer
-                         .build(
-                           "admin",
-                           config.http,
-                           config.openApi,
-                           infos,
-                           obs,
-                           controllers.flatten
-                         )
+                         .build("admin", config.http, config.openApi, infos, obs, controllers.flatten)
                          .onFinalizeCase:
                              case ExitCase.Errored(e) => error(s"Admin server stopped with error: $e")
                              case _                   => info("Admin server stopped")
                          .useForever
             yield ()
-        else IO.unit
-        end if
+            end for
     end start
 end AdminServer
 
 object AdminServer:
-    val baseEndpoint: Endpoint[Unit, Unit, (StatusCode, PillarsError.View), Unit, Any] =
+    val baseEndpoint: Endpoint[Unit, Unit, HttpErrorResponse, Unit, Any] =
         endpoint.in("admin").errorOut(PillarsError.View.output)
 
     final case class Config(
@@ -55,7 +40,7 @@ object AdminServer:
         openApi: HttpServer.Config.OpenAPI = HttpServer.Config.OpenAPI()
     ) extends pillars.Config
 
-    given Configuration = Configuration.default.withKebabCaseMemberNames.withKebabCaseConstructorNames.withDefaults
+    given Configuration = pillars.Config.defaultCirceConfig
     given Codec[Config] = Codec.AsObject.derivedConfigured
 
     private val defaultHttp = HttpServer.Config(

modules/core/src/main/scala/pillars/ApiServer.scala

@@ -22,30 +22,22 @@ trait ApiServer:
     def start(endpoints: List[HttpEndpoint]): IO[Unit]
 
     @targetName("startWithEndpoints")
-    def start(endpoints: HttpEndpoint*): IO[Unit] =
-        start(endpoints.toList)
+    def start(endpoints: HttpEndpoint*): IO[Unit] = start(endpoints.toList)
 
     @targetName("startWithControllers")
-    def start(controllers: Controller*): IO[Unit] =
-        start(controllers.toList.flatten)
+    def start(controllers: Controller*): IO[Unit] = start(controllers.toList.flatten)
 
 end ApiServer
 
 def server(using p: Pillars): Run[ApiServer] = p.apiServer
 
 object ApiServer:
-    def init(
-        config: Config,
-        infos: AppInfo,
-        observability: Observability,
-        logger: Scribe[IO]
-    ): ApiServer =
+    def init(config: Config, infos: AppInfo, observability: Observability, logger: Scribe[IO]): ApiServer =
         (endpoints: List[HttpEndpoint]) =>
             IO.whenA(config.enabled):
                 for
                     _ <- logger.info(s"Starting API server on ${config.http.host}:${config.http.port}")
-                    _ <- HttpServer
-                             .build("api", config.http, config.openApi, infos, observability, endpoints)
+                    _ <- HttpServer.build("api", config.http, config.openApi, infos, observability, endpoints)
                              .onFinalizeCase:
                                  case ExitCase.Errored(e) => logger.error(s"API server stopped with error: $e")
                                  case _                   => logger.info("API server stopped")
@@ -62,14 +54,10 @@ object ApiServer:
         openApi: HttpServer.Config.OpenAPI = HttpServer.Config.OpenAPI()
     ) extends pillars.Config
 
-    given Configuration = Configuration.default.withKebabCaseMemberNames.withKebabCaseConstructorNames.withDefaults
+    given Configuration = pillars.Config.defaultCirceConfig
     given Codec[Config] = Codec.AsObject.derivedConfigured
 
-    private val defaultHttp = HttpServer.Config(
-      host = host"0.0.0.0",
-      port = port"9876",
-      logging = Logging.HttpConfig()
-    )
+    private val defaultHttp = HttpServer.Config(host = host"0.0.0.0", port = port"9876", logging = Logging.HttpConfig())
 
     def noop: ApiServer = _ => IO.unit
 end ApiServer

modules/core/src/main/scala/pillars/Config.scala

@@ -30,6 +30,8 @@ def config(using p: Pillars): Config.PillarsConfig = p.config
 trait Config
 
 object Config:
+    val defaultCirceConfig: Configuration =
+        Configuration.default.withSnakeCaseMemberNames.withSnakeCaseConstructorNames.withDefaults
     case class PillarsConfig(
         name: App.Name,
         log: Logging.Config = Logging.Config(),
@@ -39,7 +41,7 @@ object Config:
     ) extends pillars.Config
 
     object PillarsConfig:
-        given Configuration          = Configuration.default.withKebabCaseMemberNames.withKebabCaseConstructorNames.withDefaults
+        given Configuration          = defaultCirceConfig
         given Decoder[PillarsConfig] = Decoder.derivedConfigured
         given Encoder[PillarsConfig] = Encoder.AsObject.derivedConfigured
     end PillarsConfig
@@ -53,8 +55,7 @@ object Config:
         private def readConfig[T: Decoder](using Files[IO]): Resource[IO, Either[ParsingFailure, Json]] =
             Resource.eval(Files[IO].readUtf8(path)
                 .map(regex.replaceAllIn(_, matcher))
-                .map: input =>
-                    Parser.default.parse(input)
+                .map(Parser.default.parse)
                 .compile
                 .onlyOrError)
 
@@ -75,12 +76,10 @@ object Config:
     end Reader
 
     final case class Redacted[T](value: T) extends AnyVal:
-        override def toString: String =
-            s"REDACTED"
+        override def toString: String = s"REDACTED"
 
     object Redacted:
         given [T: Decoder: Show]: Decoder[Redacted[T]] = summon[Decoder[T]].map(Redacted.apply)
-
         given [T: Encoder: Show]: Encoder[Redacted[T]] = summon[Encoder[T]].contramap(_.value)
     end Redacted
 
@@ -92,7 +91,6 @@ object Config:
 
     object Secret:
         given [T: Decoder]: Decoder[Secret[T]] = summon[Decoder[T]].map(Secret.apply)
-
         given [T: Encoder]: Encoder[Secret[T]] = summon[Encoder[T]].contramap(_.value)
     end Secret
 

modules/core/src/main/scala/pillars/HttpServer.scala

@@ -108,31 +108,25 @@ object HttpServer:
             ): IO[Option[ValuedEndpointOutput[?]]] =
                 def handlePillarsError(e: PillarsError) =
                     Some(ValuedEndpointOutput(statusCode.and(jsonBody[PillarsError.View]), (e.status, e.view)))
-                tracer
-                    .currentSpanOrNoop
+                tracer.currentSpanOrNoop
                     .flatMap: span =>
                         for
                             _ <- span.recordException(ctx.e)
                             _ <- span.addAttributes(Observability.Attributes.fromError(ctx.e))
                             _ <- span.setStatus(StatusCode.Error, ctx.e.getMessage)
                         yield ctx.e match
-                            case e: PillarsError                            =>
-                                handlePillarsError(e)
+                            case e: PillarsError                            => handlePillarsError(e)
                             case StreamMaxLengthExceededException(maxBytes) =>
                                 handlePillarsError(PillarsError.PayloadTooLarge(maxBytes))
                             case _                                          =>
                                 handlePillarsError(PillarsError.fromThrowable(ctx.e))
             end apply
 
-    final case class Config(
-        host: Host,
-        port: Port,
-        logging: Logging.HttpConfig = Logging.HttpConfig()
-    ) extends pillars.Config
+    final case class Config(host: Host, port: Port, logging: Logging.HttpConfig = Logging.HttpConfig())
+        extends pillars.Config
 
     object Config:
-        given Configuration = Configuration.default.withKebabCaseMemberNames.withKebabCaseConstructorNames.withDefaults
-
+        given Configuration         = pillars.Config.defaultCirceConfig
         given Codec[Config.OpenAPI] = Codec.AsObject.derivedConfigured
         given Codec[Config]         = Codec.AsObject.derivedConfigured
 
@@ -144,6 +138,5 @@ object HttpServer:
             useRelativePaths: Boolean = true,
             showExtensions: Boolean = false
         )
-
     end Config
 end HttpServer

modules/core/src/main/scala/pillars/Logging.scala

@@ -30,11 +30,8 @@ object Logging:
           scribe.Logger.root
               .clearHandlers()
               .clearModifiers()
-              .withHandler(
-                formatter = config.format.formatter,
-                minimumLevel = Some(config.level),
-                writer = writer(config)
-              ).replace()
+              .withHandler(config.format.formatter, writer(config), Some(config.level))
+              .replace()
         ).void
 
     private def writer(config: Config): Writer =
@@ -73,17 +70,10 @@ object Logging:
 
         given Encoder[Format] = Encoder.encodeString.contramap(_.toString.toLowerCase)
 
-        given Decoder[Format] = Decoder.decodeString.emap {
-            case "json"     => Right(Format.Json)
-            case "simple"   => Right(Format.Simple)
-            case "colored"  => Right(Format.Colored)
-            case "classic"  => Right(Format.Classic)
-            case "compact"  => Right(Format.Compact)
-            case "enhanced" => Right(Format.Enhanced)
-            case "advanced" => Right(Format.Advanced)
-            case "strict"   => Right(Format.Strict)
-            case other      => Left(s"Unknown output format: $other")
-        }
+        given Decoder[Format] = Decoder.decodeString.emap: s =>
+            Format.values.find(_.toString.equalsIgnoreCase(s)) match
+                case Some(format) => Right(format)
+                case None         => Left(s"Unknown output format: $s")
     end Format
 
     enum Output:
@@ -130,13 +120,10 @@ object Logging:
     ) extends pillars.Config
 
     object Config:
-        given Configuration = Configuration.default.withKebabCaseMemberNames.withKebabCaseConstructorNames.withDefaults
-
+        given Configuration  = pillars.Config.defaultCirceConfig
         given Decoder[Level] = Decoder.decodeString.emap(s => Level.get(s).toRight(s"Invalid log level $s"))
-
         given Encoder[Level] = Encoder.encodeString.contramap(_.name)
-
-        given Codec[Config] = Codec.AsObject.derivedConfigured
+        given Codec[Config]  = Codec.AsObject.derivedConfigured
     end Config
 
     final case class HttpConfig(

modules/core/src/main/scala/pillars/Observability.scala

@@ -92,7 +92,7 @@ object Observability:
     end Config
 
     object Config:
-        given Configuration = Configuration.default.withKebabCaseMemberNames.withKebabCaseConstructorNames.withDefaults
+        given Configuration = pillars.Config.defaultCirceConfig
         given Codec[Config] = Codec.AsObject.derivedConfigured
 
         final case class Metrics(

modules/core/src/main/scala/pillars/PillarsError.scala

@@ -17,6 +17,8 @@ import sttp.tapir.Schema
 import sttp.tapir.json.circe.jsonBody
 import sttp.tapir.statusCode
 
+type HttpErrorResponse = (StatusCode, PillarsError.View)
+
 trait PillarsError extends Throwable, NoStackTrace:
     def code: Code
     def number: ErrorNumber
@@ -25,7 +27,7 @@ trait PillarsError extends Throwable, NoStackTrace:
     def status: StatusCode          = StatusCode.InternalServerError
     override def getMessage: String = f"$code-$number%04d : $message"
 
-    def httpResponse[T]: Either[(StatusCode, PillarsError.View), T] =
+    def httpResponse[T]: Either[HttpErrorResponse, T] =
         Left((status, PillarsError.View(f"$code-$number%04d", message, details)))
 
     def view: PillarsError.View = PillarsError.View(f"$code-$number%04d", message, details)
@@ -39,7 +41,7 @@ object PillarsError:
             case _                   => Unknown(throwable)
     case class View(code: String, message: String, details: Option[String]) derives Codec.AsObject, Schema
     object View:
-        val output: EndpointOutput[(StatusCode, View)] = statusCode.and(jsonBody[View])
+        val output: EndpointOutput[HttpErrorResponse] = statusCode.and(jsonBody[View])
 
     private final case class Unknown(reason: Throwable) extends PillarsError:
         override def code: Code              = Code("ERR")

modules/core/src/main/scala/pillars/app.scala

@@ -41,17 +41,14 @@ abstract class IOApp(override val modules: ModuleSupport*) extends App(modules*)
 object App:
     private type NameConstraint = Not[Blank]
     opaque type Name <: String  = String :| NameConstraint
-
     object Name extends RefinedTypeOps[String, NameConstraint, Name]
 
     private type VersionConstraint = SemanticVersion
     opaque type Version <: String  = String :| VersionConstraint
-
     object Version extends RefinedTypeOps[String, VersionConstraint, Version]
 
     private type DescriptionConstraint = Not[Blank]
     opaque type Description <: String  = String :| DescriptionConstraint
-
     object Description extends RefinedTypeOps[String, DescriptionConstraint, Description]
 end App
 

modules/core/src/main/scala/pillars/codec.scala

@@ -19,21 +19,19 @@ import scala.concurrent.duration.FiniteDuration
 import scala.jdk.DurationConverters.*
 
 object codec:
+    given Configuration = pillars.Config.defaultCirceConfig
 
     given Decoder[Path] = Decoder.decodeString.emap(t => Right(Path(t)))
-
     given Encoder[Path] = Encoder.encodeString.contramap(_.toString)
 
     given Decoder[Host] = Decoder.decodeString.emap(t => Host.fromString(t).toRight("Failed to parse Host"))
-
     given Encoder[Host] = Encoder.encodeString.contramap(_.toString)
 
     given Decoder[Port] = Decoder.decodeInt.emap(t => Port.fromInt(t).toRight("Failed to parse Port"))
-
     given Encoder[Port] = Encoder.encodeInt.contramap(_.value)
 
     given Codec[Uri] = Codec.from(
-      Decoder.decodeString.emap(t => Uri.fromString(t).leftMap(f => f.details)),
+      Decoder.decodeString.emap(t => Uri.fromString(t).leftMap(_.details)),
       Encoder.encodeString.contramap(_.toString)
     )
 
@@ -60,5 +58,4 @@ object codec:
         case other if other.eq(Duration.Undefined) => "undefined".asJson
         case other                                 => other.toString.asJson
 
-    given Configuration = Configuration.default.withKebabCaseMemberNames.withKebabCaseConstructorNames.withDefaults
 end codec