Repository files navigation

This project comprises the core C++ HTTP abstractions used atFacebook. Internally, it is used as the basis for building many HTTPservers, proxies, and clients. This release focuses on the common HTTPabstractions and our simple HTTPServer framework. Future releases willprovide simple client APIs as well. The framework supports HTTP/1.1,SPDY/3, SPDY/3.1, HTTP/2, and HTTP/3. The goal is to provide a simple,performant, and modern C++ HTTP library.

We have a Google group for general discussions athttps://groups.google.com/d/forum/facebook-proxygen.

Theoriginal blog postalso has more background on the project.

Note that currently this project has been tested on Ubuntu 18.04 and Mac OSXalthough it likely works on many other platforms.

You will need at least 3 GiB of memory to compileproxygen and itsdependencies.

Just run./build.sh from theproxygen/ directory to get and build allthe dependencies andproxygen. You can run the tests manually withcd _build/ && make test.Then run./install.sh to install it. You can remove the temporary build directory (_build) and./build.sh && ./install.shto rebase the dependencies, and then rebuild and reinstallproxygen.

You can download and install proxygen using thevcpkg dependency manager:

git clone https://github.com/Microsoft/vcpkg.gitcd vcpkg./bootstrap-vcpkg.sh./vcpkg integrate install./vcpkg install proxygen

The proxygen port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, pleasecreate an issue or pull request on the vcpkg repository.

If you are running on another platform, you may need to install severalpackages first. Proxygen andfolly are all Autotools based projects.

Directory structure and contents:

The central abstractions to understand inproxygen/lib are the session, codec,transaction, and handler. These are the lowest level abstractions, and wedon't generally recommend building off of these directly.

When bytes are read off the wire, theHTTPCodec stored insideHTTPSession parses these into higher-level objects and associates withit a transaction identifier. The codec then calls intoHTTPSession whichis responsible for maintaining the mapping between transaction identifierandHTTPTransaction objects. Each HTTP request/response pair has aseparateHTTPTransaction object. Finally,HTTPTransaction forwards thecall to a handler object which implementsHTTPTransaction:: Handler. Thehandler is responsible for implementing business logic for the request orresponse.

The handler then calls back into the transaction to generate egress(whether the egress is a request or response). The call flows from thetransaction back to the session, which uses the codec to convert thehigher-level semantics of the particular call into the appropriate bytesto send on the wire.

The same handler and transaction interfaces are used to both create requestsand handle responses. The API is generic enough to allowboth.HTTPSession is specialized slightly differently depending onwhether you are using the connection to issue or respond to HTTPrequests.

Moving into higher levels of abstraction,proxygen/HTTP server has asimpler set of APIs and is the recommended way to interface withproxygenwhen acting as a server if you don't need the full control of the lowerlevel abstractions.

The basic components here areHTTPServer,RequestHandlerFactory, andRequestHandler. AnHTTPServer takes some configuration and is given aRequestHandlerFactory. Once the server is started, the installedRequestHandlerFactory spawns aRequestHandler for each HTTPrequest.RequestHandler is a simple interface users of the libraryimplement. Subclasses ofRequestHandler should use the inheritedprotected memberResponseHandler* downstream_ to send the response.

Proxygen is a library. After installing it, you can build your C++server. Trycd ing to the directory containing the echo server atproxygen/httpserver/samples/echo/.

After building proxygen you can start the echo server with_build/proxygen/httpserver/proxygen_echoand verify it works using curl in a different terminal:

$ curl -v http://localhost:11000/*   Trying 127.0.0.1...* Connected to localhost (127.0.0.1) port 11000 (#0)> GET / HTTP/1.1> User-Agent: curl/7.35.0> Host: localhost:11000> Accept:*/*>< HTTP/1.1 200 OK< Request-Number: 1< Date: Thu, 30 Oct 2014 17:07:36 GMT< Connection: keep-alive< Content-Length: 0<* Connection#0 to host localhost left intact

You can find other samples:

• a simple server that supports HTTP/2 server push (_build/proxygen/httpserver/proxygen_push),
• a simple server for static files (_build/proxygen/httpserver/proxygen_static)
• a simple fwdproxy (_build/proxygen/httpserver/proxygen_proxy)
• a curl-like client (_build/proxygen/httpclient/samples/curl/proxygen_curl)

Proxygen supports HTTP/3!

It depends on Facebook'smvfstlibrary for theIETF QUIC transportimplementation.

This comes with a handy command-line utility that can be used as an HTTP/3server and client.

Sample usage:

_build/proxygen/httpserver/hq --mode=server_build/proxygen/httpserver/hq --mode=client --path=/

The utility supports theqloglogging format; just start the server with the--qlogger_path option and manyknobs to tune both the quic transport and the http layer.

We use Doxygen for Proxygen's internal documentation. You can generate acopy of these docs by runningdoxygen Doxyfile from the projectroot. You'll want to look athtml/namespaceproxygen.html to start. Thiswill also generatefolly documentation.

SeeLICENSE.

Contributions to Proxygen are more than welcome.Read the guidelines in CONTRIBUTING.md.Make sure you'vesigned the CLA before sending in a pull request.

Facebook has abounty program forthe safe disclosure of security bugs. If you find a vulnerability, pleasego through the process outlined on that page and do not file a public issue.