akka / akka/akka-http

Add documentation section about what to expect from akka-http client

Open
#741 3 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

1 - triaged t:client t:docs
Dominant language
Scala
Stars
1.4k
Forks
584
Avg merge
14h 33m
Merged PRs (30d)
24

Description

Lots of people come from using either JDK's UrlConnection or AsyncHttpClient. AFAIK both of them do not queue requests somewhere but either use a pooled connection, open up a new connection, or fail directly. It should be made clear that having a big (or even unlimited connection pool per host which AHC seems to set by default), isn't fair to a server, the connection, and might not even be the fastest way to run requests.

Our default settings and behavior differ with those libraries:

  • default maximum of only 4 connections per host
  • default maximum of only 32 ongoing requests (max-open-requests)
  • way of backpressuring requests if the user code supports it via streaming APIs

We might consider increasing the defaults, though increasing the number of buffered, undispatched requests might not improve things.

This should probably tie in with #738.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Review the existing akka-http client documentation and issue #738 first. Add a section explaining the default four connections per host, 32 ongoing requests, request backpressure through streaming APIs, and how this differs from UrlConnection and AsyncHttpClient. Done means the documented defaults, behavior, and fairness considerations are clear to client users.

Written by the indexing model from the issue text.

Assessment

Tech stack
scala
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.