{"id":19848523,"url":"https://github.com/polynote/uzhttp","last_synced_at":"2025-05-01T22:30:35.171Z","repository":{"id":45155426,"uuid":"246943163","full_name":"polynote/uzhttp","owner":"polynote","description":"Minimal HTTP server for Scala+ZIO","archived":false,"fork":false,"pushed_at":"2022-02-04T11:23:57.000Z","size":24271,"stargazers_count":98,"open_issues_count":5,"forks_count":18,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-06T18:50:29.725Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/polynote.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}},"created_at":"2020-03-12T22:40:22.000Z","updated_at":"2024-07-31T17:25:56.000Z","dependencies_parsed_at":"2022-09-01T10:50:35.241Z","dependency_job_id":null,"html_url":"https://github.com/polynote/uzhttp","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polynote%2Fuzhttp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polynote%2Fuzhttp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polynote%2Fuzhttp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polynote%2Fuzhttp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/polynote","download_url":"https://codeload.github.com/polynote/uzhttp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251954664,"owners_count":21670846,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-11-12T13:17:31.687Z","updated_at":"2025-05-01T22:30:30.163Z","avatar_url":"https://github.com/polynote.png","language":"Scala","readme":"# uzhttp\n![Scala CI](https://github.com/polynote/uzhttp/workflows/Scala%20CI/badge.svg)\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/org.polynote/uzhttp_2.11/badge.svg)](https://mvnrepository.com/artifact/org.polynote/uzhttp)\n\nThis (Micro-Z-HTTP, or \"uzi-HTTP\" if you like) is a minimal HTTP server using [ZIO](https://github.com/zio/zio). It has\nessentially no features. You probably shouldn't use it.\n\n## Why?\n\nThis was made to support the HTTP serving needs of [Polynote](https://github.com/polynote/polynote) – which are minimal,\nbecause Polynote is a single-page app that only needs to serve some static files and handle websockets. As a result,\nthis is basically all that uzhttp supports.\n\n## Should I use it?\n\nProbably not! Here are just a few better options:\n\n* If you want a full-featured HTTP server which is battle-tested, built on robust technology, supports middleware, and\n  has a purely functional API with a nice DSL, go for [http4s](https://github.com/http4s/http4s) – it has pretty good\n  interoperability with ZIO by using [zio-interop-cats](https://github.com/zio/interop-cats).\n* If you want the above features but with a native ZIO solution, wait for [zio-web](https://github.com/zio/zio-web).\n* If you want a more minimal solution, that's still got a prinicpled, purely functional API but is production-ready and\n  properly engineered, take a look at [finch](https://github.com/finagle/finch).\n\n### I'm still considering uzhttp. What are its features?\n\n* Uses 100% non-blocking NIO for its networking (after it's bound, anyway), so it won't gobble up your blocking thread\n  pool.\n* Supports the basic HTTP request types as well as basic websockets.\n* Has no dependencies other than zio and zio-streams.\n\n### What important features does it lack?\n\n* Does not handle fancy new-fangled HTTP 1.1 things like chunked transfer encoding of requests (or responses, unless you\n  build it yourself).\n* Does not support SSL. Nobody really wants to deal with Java's SSL stuff, so the idea is that the app will be behind a\n  reverse proxy that deals with things like SSL termination, SSO, etc.\n* No fancy routing DSL whatsover. It takes a function that gets a request and returns a `ZIO[R, HTTPError, Response]`\n  and that's basically it.\n* There's nothing else provided for you, either. No authentication stuff built-in (you're using a proxy, remember?). No\n  pluggable middleware or things like that. It won't even parse request URIs into meaningful pieces for you. It's\n  request to response; anything else is yours to deal with.\n\n\n## How do I use it?\n\nTo create a server, you use the `uzhttp.server.Server.builder` constructor. This gives you a builder, which has methods to\nspecify where to listen, how to respond to requests, and how to handle errors. Once you've done that, you call `serve`\nwhich gives you a `ZManaged[R with Blocking, Throwable, Server]`. You can either `useForever` this (if you don't need\nto do anything else with the server), or you can `use` it as long as you end with `awaitShutdown`:\n\n```scala\nserverM.use {\n  server =\u003e log(\"It's alive!\") *\u003e server.awaitShutdown\n}\n```\n\nThe `Blocking` required for these operations is used for:\n- Binding to the given port\n- Selecting from NIO\n- Some file operations (for generating responses with the `Response` API) which are more efficient when using blocking\n  (You can avoid these if you wish, and generate your own responses).\n\nHere's an example:\n\n```scala\nimport java.net.InetSocketAddress\nimport uzhttp.server.Server\nimport uzhttp.{Request, Response, RefineOps}\nimport uzhttp.websocket.Frame\nimport zio.{App, ZIO, Task}\n\nobject ExampleServer extends App {\n  override def run(args:  List[String]): ZIO[zio.ZEnv, Nothing, Int] =\n    Server.builder(new InetSocketAddress(\"127.0.0.1\", 8080))\n      .handleSome {\n        case req if req.uri.getPath startsWith \"/static\" =\u003e\n          // deliver a static file from an application resource\n          Response.fromResource(s\"staticFiles${req.uri}\", req).refineHTTP(req)\n        case req if req.uri.getPath == \"/\" =\u003e\n          // deliver a constant HTML response\n          ZIO.succeed(Response.html(\"\u003chtml\u003e\u003cbody\u003e\u003ch1\u003eHello world!\u003c/h1\u003e\u003c/body\u003e\u003c/html\u003e\"))\n        case req@Request.WebsocketRequest(_, uri, _, _, inputFrames)\n          if uri.getPath startsWith \"/ws\" =\u003e\n          // inputFrames are the incoming frames; construct a websocket session\n          // by giving a stream of output frames\n          Response.websocket(req, inputFrames.mapM(respondToWebsocketFrame))\n      }.serve.useForever.orDie\n\n  def respondToWebsocketFrame(frame: Frame): Task[Frame] = ???\n}\n```\n\n## Can I make a pull request?\n\nAbsolutely! Please follow the [Polynote contributing guide](https://github.com/polynote/polynote/blob/master/CONTRIBUTING.md).\nWe'll gladly accept bugfixes, performance improvements, and tests; and we'd love to see features like:\n\n* Better support of HTTP features (e.g. `Transfer-Encoding`).\n* Better support of websockets (e.g. `permessage-deflate`).\n\nuzhttp would like to stay reasonably minimal. At the time of initial commit, uzhttp was under 1k lines of code! If\nyou've got a great routing DSL or other conveniences, we'll gladly take a look if it's pretty small. But we might\nsuggest that it live as a separate library.\n\n## License\n\nThis project is licensed under the Apache 2 license:\n\n\u003e Apache License\n\u003e ==============\n\u003e \n\u003e _Version 2.0, January 2004_  \n\u003e _[http://www.apache.org/licenses/](http://www.apache.org/licenses/)_\n\u003e \n\u003e ### Terms and Conditions for use, reproduction, and distribution\n\u003e \n\u003e #### 1. Definitions\n\u003e \n\u003e “License” shall mean the terms and conditions for use, reproduction, and\n\u003e distribution as defined by Sections 1 through 9 of this document.\n\u003e \n\u003e “Licensor” shall mean the copyright owner or entity authorized by the copyright\n\u003e owner that is granting the License.\n\u003e \n\u003e “Legal Entity” shall mean the union of the acting entity and all other entities\n\u003e that control, are controlled by, or are under common control with that entity.\n\u003e For the purposes of this definition, “control” means **(i)** the power, direct or\n\u003e indirect, to cause the direction or management of such entity, whether by\n\u003e contract or otherwise, or **(ii)** ownership of fifty percent (50%) or more of the\n\u003e outstanding shares, or **(iii)** beneficial ownership of such entity.\n\u003e \n\u003e “You” (or “Your”) shall mean an individual or Legal Entity exercising\n\u003e permissions granted by this License.\n\u003e \n\u003e “Source” form shall mean the preferred form for making modifications, including\n\u003e but not limited to software source code, documentation source, and configuration\n\u003e files.\n\u003e \n\u003e “Object” form shall mean any form resulting from mechanical transformation or\n\u003e translation of a Source form, including but not limited to compiled object code,\n\u003e generated documentation, and conversions to other media types.\n\u003e \n\u003e “Work” shall mean the work of authorship, whether in Source or Object form, made\n\u003e available under the License, as indicated by a copyright notice that is included\n\u003e in or attached to the work (an example is provided in the Appendix below).\n\u003e \n\u003e “Derivative Works” shall mean any work, whether in Source or Object form, that\n\u003e is based on (or derived from) the Work and for which the editorial revisions,\n\u003e annotations, elaborations, or other modifications represent, as a whole, an\n\u003e original work of authorship. For the purposes of this License, Derivative Works\n\u003e shall not include works that remain separable from, or merely link (or bind by\n\u003e name) to the interfaces of, the Work and Derivative Works thereof.\n\u003e \n\u003e “Contribution” shall mean any work of authorship, including the original version\n\u003e of the Work and any modifications or additions to that Work or Derivative Works\n\u003e thereof, that is intentionally submitted to Licensor for inclusion in the Work\n\u003e by the copyright owner or by an individual or Legal Entity authorized to submit\n\u003e on behalf of the copyright owner. For the purposes of this definition,\n\u003e “submitted” means any form of electronic, verbal, or written communication sent\n\u003e to the Licensor or its representatives, including but not limited to\n\u003e communication on electronic mailing lists, source code control systems, and\n\u003e issue tracking systems that are managed by, or on behalf of, the Licensor for\n\u003e the purpose of discussing and improving the Work, but excluding communication\n\u003e that is conspicuously marked or otherwise designated in writing by the copyright\n\u003e owner as “Not a Contribution.”\n\u003e \n\u003e “Contributor” shall mean Licensor and any individual or Legal Entity on behalf\n\u003e of whom a Contribution has been received by Licensor and subsequently\n\u003e incorporated within the Work.\n\u003e \n\u003e #### 2. Grant of Copyright License\n\u003e \n\u003e Subject to the terms and conditions of this License, each Contributor hereby\n\u003e grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,\n\u003e irrevocable copyright license to reproduce, prepare Derivative Works of,\n\u003e publicly display, publicly perform, sublicense, and distribute the Work and such\n\u003e Derivative Works in Source or Object form.\n\u003e \n\u003e #### 3. Grant of Patent License\n\u003e \n\u003e Subject to the terms and conditions of this License, each Contributor hereby\n\u003e grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,\n\u003e irrevocable (except as stated in this section) patent license to make, have\n\u003e made, use, offer to sell, sell, import, and otherwise transfer the Work, where\n\u003e such license applies only to those patent claims licensable by such Contributor\n\u003e that are necessarily infringed by their Contribution(s) alone or by combination\n\u003e of their Contribution(s) with the Work to which such Contribution(s) was\n\u003e submitted. If You institute patent litigation against any entity (including a\n\u003e cross-claim or counterclaim in a lawsuit) alleging that the Work or a\n\u003e Contribution incorporated within the Work constitutes direct or contributory\n\u003e patent infringement, then any patent licenses granted to You under this License\n\u003e for that Work shall terminate as of the date such litigation is filed.\n\u003e \n\u003e #### 4. Redistribution\n\u003e \n\u003e You may reproduce and distribute copies of the Work or Derivative Works thereof\n\u003e in any medium, with or without modifications, and in Source or Object form,\n\u003e provided that You meet the following conditions:\n\u003e \n\u003e * **(a)** You must give any other recipients of the Work or Derivative Works a copy of\n\u003e this License; and\n\u003e * **(b)** You must cause any modified files to carry prominent notices stating that You\n\u003e changed the files; and\n\u003e * **(c)** You must retain, in the Source form of any Derivative Works that You distribute,\n\u003e all copyright, patent, trademark, and attribution notices from the Source form\n\u003e of the Work, excluding those notices that do not pertain to any part of the\n\u003e Derivative Works; and\n\u003e * **(d)** If the Work includes a “NOTICE” text file as part of its distribution, then any\n\u003e Derivative Works that You distribute must include a readable copy of the\n\u003e attribution notices contained within such NOTICE file, excluding those notices\n\u003e that do not pertain to any part of the Derivative Works, in at least one of the\n\u003e following places: within a NOTICE text file distributed as part of the\n\u003e Derivative Works; within the Source form or documentation, if provided along\n\u003e with the Derivative Works; or, within a display generated by the Derivative\n\u003e Works, if and wherever such third-party notices normally appear. The contents of\n\u003e the NOTICE file are for informational purposes only and do not modify the\n\u003e License. You may add Your own attribution notices within Derivative Works that\n\u003e You distribute, alongside or as an addendum to the NOTICE text from the Work,\n\u003e provided that such additional attribution notices cannot be construed as\n\u003e modifying the License.\n\u003e \n\u003e You may add Your own copyright statement to Your modifications and may provide\n\u003e additional or different license terms and conditions for use, reproduction, or\n\u003e distribution of Your modifications, or for any such Derivative Works as a whole,\n\u003e provided Your use, reproduction, and distribution of the Work otherwise complies\n\u003e with the conditions stated in this License.\n\u003e \n\u003e #### 5. Submission of Contributions\n\u003e \n\u003e Unless You explicitly state otherwise, any Contribution intentionally submitted\n\u003e for inclusion in the Work by You to the Licensor shall be under the terms and\n\u003e conditions of this License, without any additional terms or conditions.\n\u003e Notwithstanding the above, nothing herein shall supersede or modify the terms of\n\u003e any separate license agreement you may have executed with Licensor regarding\n\u003e such Contributions.\n\u003e \n\u003e #### 6. Trademarks\n\u003e \n\u003e This License does not grant permission to use the trade names, trademarks,\n\u003e service marks, or product names of the Licensor, except as required for\n\u003e reasonable and customary use in describing the origin of the Work and\n\u003e reproducing the content of the NOTICE file.\n\u003e \n\u003e #### 7. Disclaimer of Warranty\n\u003e \n\u003e Unless required by applicable law or agreed to in writing, Licensor provides the\n\u003e Work (and each Contributor provides its Contributions) on an “AS IS” BASIS,\n\u003e WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied,\n\u003e including, without limitation, any warranties or conditions of TITLE,\n\u003e NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are\n\u003e solely responsible for determining the appropriateness of using or\n\u003e redistributing the Work and assume any risks associated with Your exercise of\n\u003e permissions under this License.\n\u003e \n\u003e #### 8. Limitation of Liability\n\u003e \n\u003e In no event and under no legal theory, whether in tort (including negligence),\n\u003e contract, or otherwise, unless required by applicable law (such as deliberate\n\u003e and grossly negligent acts) or agreed to in writing, shall any Contributor be\n\u003e liable to You for damages, including any direct, indirect, special, incidental,\n\u003e or consequential damages of any character arising as a result of this License or\n\u003e out of the use or inability to use the Work (including but not limited to\n\u003e damages for loss of goodwill, work stoppage, computer failure or malfunction, or\n\u003e any and all other commercial damages or losses), even if such Contributor has\n\u003e been advised of the possibility of such damages.\n\u003e \n\u003e #### 9. Accepting Warranty or Additional Liability\n\u003e \n\u003e While redistributing the Work or Derivative Works thereof, You may choose to\n\u003e offer, and charge a fee for, acceptance of support, warranty, indemnity, or\n\u003e other liability obligations and/or rights consistent with this License. However,\n\u003e in accepting such obligations, You may act only on Your own behalf and on Your\n\u003e sole responsibility, not on behalf of any other Contributor, and only if You\n\u003e agree to indemnify, defend, and hold each Contributor harmless for any liability\n\u003e incurred by, or claims asserted against, such Contributor by reason of your\n\u003e accepting any such warranty or additional liability.\n\u003e \n\u003e _END OF TERMS AND CONDITIONS_\n\u003e \n\u003e ### APPENDIX: How to apply the Apache License to your work\n\u003e \n\u003e To apply the Apache License to your work, attach the following boilerplate\n\u003e notice, with the fields enclosed by brackets `[]` replaced with your own\n\u003e identifying information. (Don't include the brackets!) The text should be\n\u003e enclosed in the appropriate comment syntax for the file format. We also\n\u003e recommend that a file or class name and description of purpose be included on\n\u003e the same “printed page” as the copyright notice for easier identification within\n\u003e third-party archives.\n\u003e \n\u003e     Copyright 2020 uzhttp contributors\n\u003e     \n\u003e     Licensed under the Apache License, Version 2.0 (the \"License\");\n\u003e     you may not use this file except in compliance with the License.\n\u003e     You may obtain a copy of the License at\n\u003e     \n\u003e       http://www.apache.org/licenses/LICENSE-2.0\n\u003e     \n\u003e     Unless required by applicable law or agreed to in writing, software\n\u003e     distributed under the License is distributed on an \"AS IS\" BASIS,\n\u003e     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n\u003e     See the License for the specific language governing permissions and\n\u003e     limitations under the License.\n\u003e \n","funding_links":[],"categories":["网络编程"],"sub_categories":["Spring Cloud框架"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolynote%2Fuzhttp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpolynote%2Fuzhttp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolynote%2Fuzhttp/lists"}