## File: README.md

# [hyper](https://hyper.rs)

[](https://crates.io/crates/hyper)
[](https://docs.rs/hyper)
[](./LICENSE)
[](https://github.com/hyperium/hyper/actions?query=workflow%3ACI)
[![Discord chat][discord-badge]][discord-url]

A protective and efficient HTTP library for all.

- HTTP/1 and HTTP/2
- Asynchronous design
- Leading in performance
- Tested and **correct**
- Extensive production use
- Client and Server APIs

**Get started** by looking over the [guides](https://hyper.rs/guides/1/).

## "Low-level"

hyper is a relatively low-level library, meant to be a building block for
libraries and applications.

If you are looking for a convenient HTTP client, then you may wish to consider
[reqwest](https://github.com/seanmonstar/reqwest).

If you are not sure what HTTP server to choose, then you may want to consider
[axum](https://github.com/tokio-rs/axum) or
[warp](https://github.com/seanmonstar/warp), the latter taking a more functional
approach. Both are built on top of this library.

## Contributing

To get involved, take a look at [CONTRIBUTING](CONTRIBUTING.md).

If you prefer chatting, there is an active community in the [Discord server][discord-url].

## License

hyper is provided under the MIT license. See [LICENSE](LICENSE).

[discord-badge]: https://img.shields.io/discord/500028886025895936.svg?logo=discord
[discord-url]: https://discord.gg/kkwpueZ

---

## File: capi/README.md

# C API for hyper

This provides auxiliary pieces for a C API to use the hyper library.

## Unstable

The C API of hyper is currently **unstable**, which means it's not part of the semver contract as the rest of the Rust API is.

Because of that, it's only accessible if `--cfg hyper_unstable_ffi` is passed to `rustc` when compiling. The easiest way to do that is setting the `RUSTFLAGS` environment variable.

## Building

The C API is part of the Rust library, but isn't compiled by default. Using `cargo`, staring with `1.64.0`, it can be compiled with the following command:

```
RUSTFLAGS="--cfg hyper_unstable_ffi" cargo rustc --features client,http1,http2,ffi --crate-type cdylib
```

### (Optional) With `cargo-c`

If using `cargo-c`, you can build and install a shared library with the following command:

```
RUSTFLAGS="--cfg hyper_unstable_ffi" cargo cbuild --features client,http1,http2,ffi --release
```

---

## File: docs/CODE_OF_CONDUCT.md

# Code of Conduct

## Be Kind

- Don't be mean.
- Insulting anyone is prohibited.
- Harassment of any kind is prohibited.
- If another person feels uncomfortable with your remarks, stop it.
- If a moderator deems your comment or conduct as inappropriate, stop it.
- Disagreeing is fine, but keep it to technical arguments. Never attack the person.
- Give the benefit of the doubt. Assume good intentions.
- Show empathy. There are 3 interpretations to any message: what we thought, what we said, and what they understand.
- This does mean we exclude people who are not kind. We are happy to make that sacrifice.

## Or Else

- Violations of the Code of Conduct will result in 1 warning.
- If the violation is major, a moderator may just ban immediately.
- If a warning has already been given, a moderator will ban the offender.
- There is no process for appealing a ban.
- Any violations can be reported to sean@seanmonstar.com.

---

## File: docs/CODE_STYLE.md

# Code Style

hyper uses the default configuration of `rustfmt`.

## cargo fmt

`cargo fmt --all` does not work in hyper. Please use the following commands:

```txt
# Mac or Linux
rustfmt --check --edition 2021 $(git ls-files '*.rs')

# Powershell
Get-ChildItem . -Filter "*.rs" -Recurse | foreach { rustfmt --check --edition 2021 $_.FullName }
```

> **NOTE**: If you are using `rust-analyzer`, you can add the following two lines in your `settings.json` to make sure the features get taken into account when checking the project:
>
>    ```json
>     "rust-analyzer.cargo.features": ["full"],
>     "rust-analyzer.check.features": ["full"],
>    ```

---

## File: docs/COMMITS.md

# Git Commit Guidelines

We have very precise rules over how our git commit messages can be formatted.  This leads to **more
readable messages** that are easy to follow when looking through the **project history**.  But also,
we use the git commit messages to **generate the change log**.

## Commit Message Format
Each commit message consists of a **header**, a **body** and a **footer**.  The header has a special
format that includes a **type**, a **scope** and a **subject**:

```
<type>(<scope>): <subject>



<footer>
```

Any line of the commit message cannot be longer 100 characters! This allows the message to be easier
to read on github as well as in various git tools.

## Type
Must be one of the following:

* **feat**: A new feature
* **fix**: A bug fix
* **docs**: Documentation only changes
* **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing
  semi-colons, etc)
* **refactor**: A code change that neither fixes a bug or adds a feature
* **perf**: A code change that improves performance
* **test**: Adding missing tests
* **chore**: Changes to the build process or auxiliary tools and libraries such as documentation
    generation

## Scope
The scope should refer to a module in hyper that is being touched. Examples:

* client
* server
* http1
* http2
* ffi
* upgrade
* examples

## Subject

The subject contains succinct description of the change:

* use the imperative, present tense: "change" not "changed" nor "changes"
* don't capitalize first letter
* no dot (.) at the end

## Body

Just as in the **subject**, use the imperative, present tense: "change" not "changed" nor "changes"
The body should include the motivation for the change and contrast this with previous behavior.

## Footer

The footer should contain any information about **Breaking Changes** and is also the place to
reference GitHub issues that this commit **Closes**.

The last line of commits introducing breaking changes should be in the form `BREAKING CHANGE: <desc>`

---

## File: docs/GOVERNANCE.md

# Governance

## Making decisions

There's two main pieces to the way decisions are made in hyper:

1. A decision-making framework
2. The people who apply it

The people are described [lower down in this document](#roles).

### Decision-making framework

We start with the users. The project wouldn't exist without them, and it exists
in order to enable users to do amazing things with HTTP. We listen to our
users. Some actively contribute their thoughts, but many others we must seek
out to learn about their usage, joys, and headaches. Those insights allow our
experts to determine the best solutions for the users.

We then define a set of [TENETS](./TENETS.md), which are guiding principles
that can be used to measure aspects of individual decisions. It should be
possible to identify one or more tenets that apply to why a decision is made.
And the set helps us balance which priorities are more important for our users.

We combine the usecases with the tenets to come up with a [VISION](./VISION.md)
that provides a longer-term plan of what hyper _should_ look like.

Finally, we define a [ROADMAP](./ROADMAP.md) that describes what the
short-term, tactical changes to bring hyper closer in line with the vision.

## Roles

These are the roles people can fill when participating in the project. A list
of the people in each role is available in [MAINTAINERS](./MAINTAINERS.md).

### Contributor

A contributor is anyone who contributes their time to provide value for the
project. This could be in the form of code, documentation, filing issues,
discussing designs, or helping others on the issue tracker or in chat.

All contributors MUST follow the [Code of Conduct][coc].

👋  **New here?** [This could be you!][contrib]

### Triager

Triagers assess issues on the issue tracker. They help make sure the work is
well organized, and are critical for making new issue reporters feeling
welcome.

Responsibilities:

- Adhere to the [Code of Conduct][coc]
- Follow the [triager's guide][triage-guide]

Privileges:

- Can edit, label, and close issues
- Member of the organization
- Can be assigned issues and pull requests

How to become:

- Make a few [contributions][contrib] to the project, to show you can follow
  the [Code of Conduct][coc].
- Self-nominate by making a pull request adding yourself to the
  [list](./MAINTAINERS.md#triagers).


### Collaborator

Collaborators are contributors who have been helping out in a consistent basis.

Responsibilities:

- Be exemplars of the [Code of Conduct][coc]
- Internalize the [VISION](./VISION.md)
- Reviewing pull requests from other contributors
- Provide feedback on proposed features and design documents
- [Welcome new contributors][triage-guide]
- Answer questions in issues and/or chat
- Mentor contributors to become members

Privileges:

- Can review and merge pull requests
- Can trigger re-runs of CI, and approve CI for first-time contributors
- Can assign issues and pull requests to other organization members

How to become:

- Work at fulfilling the above responsibilities.
- Any collaborator may nominate a contributor who has been around for some time
  and is already filling the responsibilities.
- Another collaborator must second the nomination.
- If there are no objections, a maintainer will welcome the new collaborator.

Don't be afraid to ask a collaborator for what you could work on to reach this
goal!

### Advisor

Advisors are contributors with a lot of domain expertise. They offer advice on
proposals, complicated bugs or features, based on their experience elsewhere in
the industry.

Responsibilities:

- Adhere to the [Code of Conduct][coc]
- Try to offer advice when the `@hyperium/advisors` team is tagged for input.
  (This is not a frequent occurrence, so the time commitment should generally be
  low.)

How to become:

- Advisors are invited by a maintainer.
- Sometimes they are experienced Collaborators who must step back from active
  contributing. Sometimes they are experts placed elsehwere who are friendly to
  the project.

### Maintainer

Maintainers are the project admins. Besides being a collaborator, they take care
of house-keeping duties, help lead the direction, and have the final authority when
required.

[coc]: ./CODE_OF_CONDUCT.md
[contrib]: ../CONTRIBUTING.md
[triage-guide]: ./ISSUES.md#triaging

---

## File: docs/ISSUES.md

# Issues

The [issue tracker][issues] for hyper is where we track all features, bugs, and discuss proposals.

## Triaging

Once an issue has been opened, it is normal for there to be discussion
around it. Some contributors may have differing opinions about the issue,
including whether the behavior being seen is a bug or a feature. This
discussion is part of the process and should be kept focused, helpful, and
professional.

The objective of helping with triaging issues is to help reduce the issue
backlog and keep the issue tracker healthy, while enabling newcomers another
meaningful way to get engaged and contribute.

### Acknowledge

Acknowledge the human. This is meant actively, such as giving a welcome, or
thanks for a detailed report, or any other greeting that makes the person feel
that their contribution (issues are contributions!) is valued. It also is meant
to be internalized, and be sure to always [treat the person kindly][COC]
throughout the rest of the steps of triaging.

### Ask for more info

Frequently, we need more information than was originally provided to fully
evaluate an issue.

If it is a bug report, ask follow up questions that help us get a [minimum
reproducible example][MRE]. This may take several round-trip questions. Once
all the details are gathered, it may be helpful to edit the original issue text
to include them all.

### Categorize

Once enough information has been gathered, the issue should be categorized
with [labels](#labels). Ideally, most issues should be labelled with an area,
effort, and severity. An issue _can_ have multiple areas, pick what fits. There
should be only one severity, and the descriptions of each should help to pick
the right one. The hardest label to select is "effort". If after reading the
descriptions of each effort level, you're still unsure, you can ping a
maintainer to pick one.

### Adjust the title

An optional step when triaging is to adjust the title once more information is
known. Sometimes an issue starts as a question, and through discussion, it
turns out to be a feature request, or a bug report. In those cases, the title
should be changed from a question, and the title should be a succinct action to
be taken. For example, a question about an non-existent configuration option
may be reworded to "Add option to Client to do Zed".

### Mentoring

The last part of triaging is to try to make the issue a learning experience.
After a discussion with the reporter, it would be good to ask if they are now
interested in submitting the change described in the issue.

Otherwise, it would be best to leave the issue with a series of steps for
anyone else to try to write the change. That could be pointing out that a
design proposal is needed, addressing certain points. Or, if the required
changes are mostly know, a list of links to modules and functions where code
needs to be changed, and to what. That way we mentor newcomers to become
successful contributors of new [pull requests][PRs].

## Labels

Issues are organized with a set of labels. Most labels follow a system of being prefixed by a "type".

### Area

The area labels describe what part of hyper is relevant.

- **A-body**: streaming request and response bodies.
- **A-client**: the HTTP client.
- **A-dependencies**: library dependencies.
- **A-docs**: documentation.
- **A-error**: error reporting and types.
- **A-ffi**: the C API.
- **A-http1**: the HTTP/1 specifics.
- **A-http2**: the HTTP/2 specifics.
- **A-server**: the HTTP server.
- **A-tests**: the unit and integration tests.

### Blocked

These labels indicate an issue is "blocked" for some reason.

- **B-breaking-change**: a breaking change that is waiting for the next semver-compatible release.
- **B-rfc**: request for comments. More discussion is needed to explore the design.
- **B-upstream**: waiting on something in a dependency or the compiler.

### Category

The category marks what kind of issue this is.

- **C-bug**: something is wrong, this is bad!
- **C-feature**: this is a new feature request, adding something new.
- **C-performance**: make existing working code go faster.
- **C-refactor**: improve internal code to help readability and maintenance.
- **C-chore**: a general chore or maintenance task.

### Effort

The effort labels are a best-guess at roughly how much effort and knowledge of hyper is needed to accomplish the task.

- **E-easy**: a great starting point for a new contributor.
- **E-medium**: some knowledge of how hyper internals work would be useful.
- **E-hard**: likely requires a deeper understanding of how hyper internals work.


[issues]: https://github.com/hyperium/hyper/issues
[COC]: ./CODE_OF_CONDUCT.md
[PRs]: ./PULL_REQUESTS.md
[MRE]: https://en.wikipedia.org/wiki/Minimal_reproducible_example

---

## File: docs/MAINTAINERS.md

# The People

To see what these roles do, and how to become one, look at [GOVERNANCE](./GOVERNANCE.md).

## Triagers

- Eray Karatay (@programatik29)
- Oddbjørn Grødem (@oddgrd)

## Collaborators

- Sean McArthur (@seanmonstar)
- Steven Fackler (@sfackler)
- dswij (@dswij)
- tottoto (@tottoto)
- katelyn martin (@cratelyn)

### Collaborator emeriti

- Jonathan Reem (@reem)
- Carl Lerche (@carllerche)
- Oliver Gould (@olix0r)
- Eliza Weisman (@hawkw)
- Lucio Franco (@LucioFranco)
- Adam Foltzer (@acfoltzer)
- David Pedersen (@davidpdrsn)
- Anthony Ramine (@nox)
- Noah Kennedy (@Noah-Kennedy)

## Advisors

- Oliver Gould (@olix0r)
- Adam Foltzer (@acfoltzer)

## Maintainers

- Sean McArthur (@seanmonstar)

---

## File: docs/MSRV.md

# Minimum Support Rust Version (MSRV)

hyper's current policy is to always support a Rust version at least 6 months
old. That is, a compiler version released within the last 6 months can compile
hyper. It is possible that an older compiler can work, but that is not
guaranteed. We try to increase the MSRV responsibly, only when a significant
new feature is needed.

The current MSRV is: **1.63**.

---

## File: docs/PULL_REQUESTS.md

# Pull Requests

Pull requests are the way to submit changes to the hyper repository.

## Submitting a Pull Request

In most cases, it a good idea to discuss a potential change in an
[issue](ISSUES.md). This will allow other contributors to provide guidance and
feedback _before_ significant code work is done, and can increase the
likelihood of getting the pull request merged.

### Tests

If the change being proposed alters code (as opposed to only documentation for
example), it is either adding new functionality to hyper or it is fixing
existing, broken functionality. In both of these cases, the pull request should
include one or more tests to ensure that hyper does not regress in the future.

### Commits

Once code, tests, and documentation have been written, a commit needs to be
made. Following the [commit guidelines](COMMITS.md) will help with the review
process by making your change easier to understand, and makes it easier for
hyper to produce a valuable changelog with each release.

However, if your message doesn't perfectly match the guidelines, **do not
worry!** The person that eventually merges can easily fixup the message at that
time.

### Opening the Pull Request

From within GitHub, open a new pull request from your personal branch.

Once opened, pull requests are usually reviewed within a few days.

### Discuss and Update

You will probably get feedback or requests for changes to your Pull Request.
This is a big part of the submission process so don't be discouraged! Some
contributors may sign off on the Pull Request right away, others may have more
detailed comments or feedback. This is a necessary part of the process in order
to evaluate whether the changes are correct and necessary.

Any community member can review a PR and you might get conflicting feedback.
Keep an eye out for comments from code owners to provide guidance on
conflicting feedback.

You don't need to close the PR and create a new one to address feedback. You
may simply push new commits to the existing branch.