{"id":46128578,"url":"https://github.com/theiterators/http4s-stir","last_synced_at":"2026-03-02T03:12:27.765Z","repository":{"id":168682165,"uuid":"643620254","full_name":"theiterators/http4s-stir","owner":"theiterators","description":"http4s-stir offers Pekko HTTP-style (Akka HTTP-style) DSL directives for http4s using cats-effect's IO as an effect system","archived":false,"fork":false,"pushed_at":"2025-07-18T08:10:22.000Z","size":258,"stargazers_count":34,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-07-18T12:11:02.477Z","etag":null,"topics":["akka-http","dsl","http4s","pekko-http","scala"],"latest_commit_sha":null,"homepage":"","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/theiterators.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-05-21T18:30:11.000Z","updated_at":"2025-07-18T08:10:27.000Z","dependencies_parsed_at":null,"dependency_job_id":"c6cff984-2c27-4297-94c9-66373fb37056","html_url":"https://github.com/theiterators/http4s-stir","commit_stats":{"total_commits":66,"total_committers":3,"mean_commits":22.0,"dds":0.3787878787878788,"last_synced_commit":"09953c39ef0e5cfca427aa16a9b7cd877131c9a7"},"previous_names":["luksow/http4s-pdsl"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/theiterators/http4s-stir","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theiterators%2Fhttp4s-stir","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theiterators%2Fhttp4s-stir/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theiterators%2Fhttp4s-stir/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theiterators%2Fhttp4s-stir/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/theiterators","download_url":"https://codeload.github.com/theiterators/http4s-stir/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theiterators%2Fhttp4s-stir/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29991321,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T01:47:34.672Z","status":"online","status_checked_at":"2026-03-02T02:00:07.342Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["akka-http","dsl","http4s","pekko-http","scala"],"created_at":"2026-03-02T03:12:27.244Z","updated_at":"2026-03-02T03:12:27.747Z","avatar_url":"https://github.com/theiterators.png","language":"Scala","funding_links":[],"categories":[],"sub_categories":[],"readme":"# http4s-stir\n\nWelcome to http4s-stir, a library designed to bridge the gap between Pekko HTTP (Akka HTTP) and http4s. This README provides an overview of the library, its usage, project status, and more.\n\nhttp4s-stir offers [Pekko HTTP](https://github.com/apache/incubator-pekko-http)-style (Akka HTTP-style) DSL directives for [http4s](https://github.com/http4s/http4s) using cats-effect's IO as an effect system. About 85% of all directives have been ported. Some were omitted due to a lack of support in http4s, while others were modified to fit http4s' distinct architecture. For specifics, refer to the [Missing](#missing) section below.\n\nAdditionally, there's a compatibility layer, [`Http4sDirectives`](https://github.com/theiterators/http4s-stir/blob/master/core/src/main/scala/pl/iterators/stir/server/directives/Http4sDirectives.scala), for http4s-dsl routes.\n\nhttp4s-stir also furnishes a test kit akin to Pekko's (Akka's).\n\n## How to use it\n\n### Installation\n\nIn SBT:\n\n```scala\nlibraryDependencies += \"pl.iterators\" %% \"http4s-stir\" % \"0.4.0\"\nlibraryDependencies += \"pl.iterators\" %% \"http4s-stir-testkit\" % \"0.4.0\" % Test // if you need this\n```\n\nFor `scala-cli` see [this example](#example).\n\n### Example\n\nHere's an example in Scala 3 that you can run using scala-cli:\n\n```scala 3\n// Main.scala\n//\u003e using dep org.typelevel::cats-effect::3.5.4\n//\u003e using dep org.http4s::http4s-dsl::0.23.28\n//\u003e using dep org.http4s::http4s-ember-server::0.23.28\n//\u003e using dep org.http4s::http4s-circe::0.23.28\n//\u003e using dep io.circe::circe-core::0.14.10\n//\u003e using dep io.circe::circe-generic::0.14.10\n//\u003e using dep pl.iterators::http4s-stir::0.4.0\n\nimport org.http4s.Status\nimport org.http4s.ember.server.EmberServerBuilder\nimport org.http4s.circe.CirceEntityEncoder.*\nimport org.http4s.circe.CirceEntityDecoder.*\nimport io.circe.*\nimport io.circe.generic.semiauto.*\nimport cats.effect.IO\nimport pl.iterators.stir.server.*\nimport pl.iterators.stir.server.Directives.*\nimport cats.effect.IOApp\n\n// example rewritten from https://pekko.apache.org/docs/pekko-http/current/introduction.html#using-apache-pekko-http\nvar orders: List[Item] = Nil\n\n// domain model\nfinal case class Item(name: String, id: Long)\nfinal case class Order(items: List[Item])\n\n// formats for unmarshalling and marshalling\ngiven Codec[Item] = deriveCodec[Item]\ngiven Codec[Order] = deriveCodec[Order]\n\n// (fake) async database query api\ndef fetchItem(itemId: Long): IO[Option[Item]] = IO.delay {\n  orders.find(o =\u003e o.id == itemId)\n}\ndef saveOrder(order: Order): IO[List[Item]] = {\n  orders = order.items ::: orders\n  IO.delay(orders)\n}\n\nval route: Route =\n  concat(\n    get {\n      pathPrefix(\"item\" / LongNumber) { id =\u003e\n        // there might be no item for a given id\n        val maybeItem: IO[Option[Item]] = fetchItem(id)\n\n        onSuccess(maybeItem) {\n          case Some(item) =\u003e complete(item)\n          case None       =\u003e complete(Status.NotFound)\n        }\n      }\n    },\n    post {\n      path(\"create-order\") {\n        entity(as[Order]) { order =\u003e\n          val saved: IO[List[Item]] = saveOrder(order)\n          onSuccess(saved) {\n            _ =\u003e // we are not interested in the result value `Done` but only in the fact that it was successful\n              complete(\"order created\")\n          }\n        }\n      }\n    }\n  )\n\nobject Main extends IOApp.Simple {\n  val run = EmberServerBuilder\n          .default[IO]\n          .withHttpApp(route.toHttpRoutes.orNotFound)\n          .build\n          .use(_ =\u003e IO.never)\n}\n\n```\n\nTo run this service you can use `scala-cli run .`.\n\nOr maybe if you want, you can compile it to JS file: `scala-cli --power package --js --js-module-kind commonjs Main.scala`.\n\n```scala 3\n// Main.test.scala\n//\u003e using test.dep org.specs2::specs2-core:5.5.8\n//\u003e using test.dep pl.iterators::http4s-stir-testkit:0.4.0\n//\u003e using test.dep org.http4s::http4s-circe:0.23.28\n\nimport org.http4s.Status\nimport org.http4s.circe.CirceEntityEncoder.*\nimport org.http4s.circe.CirceEntityDecoder.*\nimport cats.effect.IO\nimport cats.effect.unsafe.IORuntime\nimport org.specs2.mutable.Specification\nimport pl.iterators.stir.testkit.Specs2RouteTest\n\nclass MainRoutesSpec extends Specification with Specs2RouteTest {\n  override implicit val runtime: IORuntime = IORuntime.global\n\n  sequential\n  \"The routes\" should {\n    \"create order\" in {\n      Post(\"/create-order\", Order(List(Item(\"foo\", 42)))) ~\u003e route ~\u003e check {\n        responseAs[String] must contain(\"order created\")\n        orders.head must beEqualTo(Item(\"foo\", 42))\n      }\n    }\n    \"retrieve an item if present\" in {\n      orders = List(Item(\"foo\", 42))\n      Get(\"/item/42\") ~\u003e route ~\u003e check {\n        responseAs[Item] must beEqualTo(Item(\"foo\", 42))\n      }\n    }\n    \"return 404 if item is not present\" in {\n      orders = List.empty\n      Get(\"/item/42\") ~\u003e route ~\u003e check {\n        status must beEqualTo(Status.NotFound)\n      }\n    }\n  }\n}\n\n```\n\nTo run the tests you can use `scala-cli test .`.\n\nFor a more comprehensive example showcasing additional directives see [examples](https://github.com/theiterators/http4s-stir/blob/master/examples/src/main/scala/Service.scala). You can run it with `~examples/reStart`.\n\n## Why this library?\n\nHere's why I embarked on this project:\n\n- After the license change for Akka, many contemplated transitioning to http4s and the Typelevel stack. I wanted to simplify this migration.\n- While I'm a fan of cats-effect, I find the http4s DSL verbose and clunky. Marrying Pekko HTTP (Akka HTTP) with cats-effect seemed inelegant, so http4s-stir could be the remedy.\n- I was curious about the internals of both Pekko HTTP and http4s and wanted to determine the feasibility of this project.\n- And, of course, a bit of playful provocation - [see the next section](#whats-with-the-name).\n\n## What's with the name?\n\n\u003e **stir something up** (pv)\n\u003e \n\u003e *to cause an unpleasant emotion or problem to begin or grow*\n\nThere are folks who adore http4s but detest Pekko's (or Akka's) DSL. Conversely, there are those who champion Pekko's (or Akka's) but disdain http4s DSL. I aimed to ruffle feathers from both camps with a hybrid library.\n\n## Project status\n\nThis library is in preview, intended to collect initial feedback. Yet, I am dedicated to its ongoing maintenance and enhancement, especially as it undergoes real-world testing. Contributions are very welcome.\n\n## Missing\n\nCertain directives from the original are either absent or have been modified:\n\n* Assuming and converting to/from strict entity\n* `CacheConditionDirectives`\n* `CodingDirectives`\n* directory listing in `FileAndResourceDirectives`\n* `RangeDirectives`\n* `checkSameOrigin` in `HeaderDirectives`\n* handling of multipart forms in `FormFieldDirectives` (but I don't like it anyway)\n* Some of how akka configures things\n  * `withSizeLimit`\n  * `withoutSizeLimit`\n  * `requestEntityEmpty`\n  * `requestEntityPresent`\n  * `rejectEmptyResponse`\n  * `extractRequestTimeout`\n  * `withRequestTimeoutResponse`\n* AttributeDirectives\n* FramedEntityStreamingDirectives\n* WebSocketDirectives in large part\n* Testkit needed significant changes\n  * Not async anymore\n  * Chunks not supported\n  * Request building incomplete (missing some minor header methods)\n  * All websocket thingies\n  * Some logic of transparent headers and default host info\n\n## Support\n\n### Encountering a Problem?\n\nIf you run into any issues, unexpected behavior, or errors, we encourage you to report them. Your feedback is invaluable and helps us improve.\n\n### Have a Feature Request?\n\nIf there's a feature you'd like to see, or if you have an idea that would make this project even better, we'd love to hear about it!\n\n### How to Report an Issue or Feature Request\n\nPlease create a new issue in our [http4-stir](https://github.com/theiterators/http4s-stir/issues). Ensure you provide as much detail as possible:\n\n1. **For issues:**\n  - Describe the issue you're facing.\n  - Steps to reproduce.\n  - Expected behavior.\n  - Actual behavior.\n\n2. **For feature requests:**\n  - Describe the feature and why you believe it would be useful.\n  - Any reference or example from other projects/tools, if applicable.\n\nBy providing detailed information, you'll help us address your concerns more efficiently.\n\nThank you for your contributions and for helping make this project better for everyone!\n\n## License\n\nhttp4s-stir is under the Apache License, Version 2.0 (\"the License\"). You must comply with this License to use this software. A [full license text](https://github.com/theiterators/http4s-stir/blob/master/LICENSE) is available in the repository.\n\n## Acknowledgements\n\nhttp4s-stir incorporates significant portions of code adapted from [Pekko HTTP](https://github.com/apache/incubator-pekko-http), a fork of [Akka HTTP](https://github.com/akka/akka-http).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheiterators%2Fhttp4s-stir","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheiterators%2Fhttp4s-stir","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheiterators%2Fhttp4s-stir/lists"}