Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/apache/pekko-http

The Streaming-first HTTP server/module of Apache Pekko
https://github.com/apache/pekko-http

http http-client http-server http2 pekko pekko-http reactive streaming websocket

Last synced: 1 day ago
JSON representation

The Streaming-first HTTP server/module of Apache Pekko

Awesome Lists containing this project

README 

        
# Apache Pekko HTTP



The Pekko HTTP modules implement a full server- and client-side HTTP stack on top

of pekko-actor and pekko-stream. It's not a web-framework but rather a more

general toolkit for providing and consuming HTTP-based services. While

interaction with a browser is of course also in scope it is not the primary

focus of Pekko HTTP.



Pekko HTTP is a fork of [Akka HTTP](https://github.com/akka/akka-http) 10.2.x release, prior to the Akka project's adoption of the Business Source License.



Pekko HTTP follows a rather open design and many times offers several different

API levels for "doing the same thing". You get to pick the API level of

abstraction that is most suitable for your application. This means that, if you

have trouble achieving something using a high-level API, there's a good chance

that you can get it done with a low-level API, which offers more flexibility but

might require you to write more application code.



## Documentation



The documentation is available at

[pekko.apache.org](https://pekko.apache.org/docs/pekko-http/current/), for

[Scala](https://pekko.apache.org/docs/pekko-http/current/scala/http/) and

[Java](https://pekko.apache.org/docs/pekko-http/current/java/http/).



## Building from Source



### Prerequisites

- Make sure you have installed a Java Development Kit (JDK) version 8 or later.

- Make sure you have [sbt](https://www.scala-sbt.org/) installed.

- [Graphviz](https://graphviz.gitlab.io/download/) is needed for the scaladoc generation build task, which is part of the release.



### h2spec



Some tests for HTTP/2 compliance use [h2spec](https://github.com/summerwind/h2spec). The sbt build downloads

pre-built binaries from the GitHub releases page for the h2spec project. These binaries are not available for all

operating systems. Apple Mac Silicon users may need to install [Rosetta](https://support.apple.com/en-us/HT211861) if

they do not have it installed already.



### Running the Build

- Open a command window and change directory to your preferred base directory

- Use git to clone the [repo](https://github.com/apache/pekko-http) or download a source release from https://pekko.apache.org (and unzip or untar it, as appropriate)

- Change directory to the directory where you installed the source (you should have a file called `build.sbt` in this directory)

- `sbt compile` compiles the main source for project default version of Scala (2.13)

    - `sbt +compile` will compile for all supported versions of Scala

- `sbt test` will compile the code and run the unit tests

- `sbt testQuick` similar to `test` but when repeated in shell mode will only run failing tests

- `sbt package` will build the jars

    - the jars will built into target dirs of the various modules

    - for the the 'http-core' module, the jar will be built to `http-core/target/scala-2.13/`

- `sbt publishLocal` will push the jars to your local Apache Ivy repository

- `sbt publishM2` will push the jars to your local Apache Maven repository

- `sbt docs/paradox` will build the docs (the ones describing the module features)

     - `sbt docs/paradoxBrowse` does the same but will open the docs in your browser when complete

     - the `index.html` file will appear in `target/paradox/site/main/`

- `sbt unidoc` will build the Javadocs for all the modules and load them to one place (may require Graphviz, see Prerequisites above)

     - the `index.html` file will appear in `target/scala-2.13/unidoc/`

- `sbt sourceDistGenerate` will generate source release to `target/dist/`

- The version number that appears in filenames and docs is derived, by default. The derived version contains the most git commit id or the date/time (if the directory is not under git control). 

    - You can set the version number explicitly when running sbt commands

        - eg `sbt "set ThisBuild / version := \"1.0.0\"; sourceDistGenerate"`  

    - Or you can add a file called `version.sbt` to the same directory that has the `build.sbt` containing something like

        - `ThisBuild / version := "1.0.0"`



## Community



If you have questions about the contribution process or discuss specific issues, please interact with the community using the following resources.



- [GitHub discussions](https://github.com/apache/pekko-http/discussions): for questions and general discussion.

- [Pekko users mailing list](https://lists.apache.org/[email protected]): for Pekko development discussions.

- [Pekko dev mailing list](https://lists.apache.org/[email protected]): for Pekko development discussions.

- [GitHub issues](https://github.com/apache/pekko-http/issues): for bug reports and feature requests. Please search the existing issues before creating new ones. If you are unsure whether you have found a bug, consider asking in GitHub discussions or the mailing list first.



## Contributing



Contributions are *very* welcome!



If you see an issue that you'd like to see fixed, the best way to make it happen is to help out by submitting a pull request.

For ideas of where to contribute, [tickets marked as "help wanted"](https://github.com/apache/pekko-http/labels/help%20wanted) are a good starting point.



Refer to the [CONTRIBUTING.md](CONTRIBUTING.md) file for more details about the workflow,

and general hints on how to prepare your pull request. You can also ask for clarifications or guidance in GitHub issues directly.



## License



Apache Pekko HTTP is Open Source and available under the Apache 2 License.