hyper Documentation

File: README.md Copy Chapter

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

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.

"Low-level" Copy Chapter

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.

If you are not sure what HTTP server to choose, then you may want to consider
axum or
warp, the latter taking a more functional
approach. Both are built on top of this library.

Contributing Copy Chapter

To get involved, take a look at CONTRIBUTING.

If you prefer chatting, there is an active community in the Discord server.

License Copy Chapter

hyper is provided under the MIT license. See LICENSE.

File: capi/README.md Copy Chapter

C API for hyper

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

Unstable Copy Chapter

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 Copy Chapter

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` Copy Section

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 Copy Chapter

Code of Conduct

Be Kind Copy Chapter

• 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 Copy Chapter

• 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 [email protected].

File: docs/CODE_STYLE.md Copy Chapter

Code Style

hyper uses the default configuration of rustfmt.

cargo fmt Copy Chapter

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

# 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 Copy

"rust-analyzer.cargo.features": ["full"],
 "rust-analyzer.check.features": ["full"],

File: docs/COMMITS.md Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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

• client
• server
• http1
• http2
• ffi
• upgrade
• examples

Subject Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

Governance

Making decisions Copy Chapter

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.

Decision-making framework Copy Section

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, 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
that provides a longer-term plan of what hyper should look like.

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

Roles Copy Chapter

These are the roles people can fill when participating in the project. A list
of the people in each role is available in MAINTAINERS.

Contributor Copy Section

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.

👋 New here? This could be you!

Triager Copy Section

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
• Follow the triager's 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 to the project, to show you can follow
  the Code of Conduct.
• Self-nominate by making a pull request adding yourself to the
  list.

Collaborator Copy Section

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

Responsibilities:

• Be exemplars of the Code of Conduct
• Internalize the VISION
• Reviewing pull requests from other contributors
• Provide feedback on proposed features and design documents
• Welcome new contributors
• 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 Copy Section

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
• 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 Copy Section

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.

File: docs/ISSUES.md Copy Chapter

Issues

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

Triaging Copy Chapter

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 Copy Section

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
throughout the rest of the steps of triaging.

Ask for more info Copy Section

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. 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 Copy Section

Once enough information has been gathered, the issue should be categorized
with 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 Copy Section

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 Copy Section

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.

Labels Copy Chapter

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

Area Copy Section

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 Copy Section

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 Copy Section

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 Copy Section

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.

File: docs/MAINTAINERS.md Copy Chapter

The People

To see what these roles do, and how to become one, look at GOVERNANCE.

Triagers Copy Chapter

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

Collaborators Copy Chapter

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

Collaborator emeriti Copy Section

• 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 Copy Chapter

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

Maintainers Copy Chapter

• Sean McArthur (@seanmonstar)

File: docs/MSRV.md Copy Chapter

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 Copy Chapter

Pull Requests

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

Submitting a Pull Request Copy Chapter

In most cases, it a good idea to discuss a potential change in an
issue. 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 Copy Section

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 Copy Section

Once code, tests, and documentation have been written, a commit needs to be
made. Following the commit guidelines 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 Copy Section

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 Copy Section

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.