Skip to content

Latest commit

 

History

History
99 lines (77 loc) · 6.12 KB

README.md

File metadata and controls

99 lines (77 loc) · 6.12 KB
Raw

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 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, for Scala and Java.

Building from Source

Prerequisites

  • Make sure you have installed a Java Development Kit (JDK) version 8 or later.
  • Make sure you have sbt installed.
  • Graphviz is needed for the scaladoc generation build task, which is part of the release.

h2spec

Some tests for HTTP/2 compliance use 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 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 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: for questions and general discussion.
  • Pekko users mailing list: for Pekko development discussions.
  • Pekko dev mailing list: for Pekko development discussions.
  • GitHub 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" are a good starting point.

Refer to the 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.