Technology moves fast! ⚑ Don't get left behind.🚢 Subscribe to our mailing list to keep up with latest and greatest in open source projects! πŸ†


Subscribe to our mailing list

proxygen

A collection of C++ HTTP libraries including an easy to use HTTP server.

Subscribe to updates I use proxygen


Statistics on proxygen

Number of watchers on Github 5427
Number of open issues 27
Average time to close an issue 26 days
Main language C++
Average time to merge a PR about 2 hours
Open pull requests 18+
Closed pull requests 54+
Last commit over 1 year ago
Repo Created almost 5 years ago
Repo Last Updated over 1 year ago
Size 4.65 MB
Organization / Authorfacebook
Contributors32
Page Updated
Do you use proxygen? Leave a review!
View open issues (27)
View proxygen activity
View on github
Fresh, new opensource launches πŸš€πŸš€πŸš€
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating proxygen for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)

Proxygen: Facebook's C++ HTTP Libraries

Build Status

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

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

The original blog post also has more background on the project.

Installing

Note that currently this project has only been tested on Ubuntu 14.04, although it likely works on many other platforms. Support for Mac OSX is incomplete.

You will need at least 3 GiB of memory to compile proxygen and its dependencies.

Easy Install

Just run ./deps.sh from the proxygen/ directory to get and build all the dependencies and proxygen. It will also run all the tests. Then run ./reinstall.sh to install it. You can run ./deps.sh && ./reinstall.sh whenever to rebase the dependencies, and then rebuild and reinstall proxygen.

A note on compatibility: this project relies on system installed folly. If you rebase proxygen and make starts to fail, you likely need to update to the latest version of folly. Running ./deps.sh && ./reinstall.sh will do this for you. We are still working on a solution to manage depencies more predictably.

Other Platforms

If you are running on another platform, you may need to install several packages first. Proxygen and folly are all autotools based projects.

Introduction

Directory structure and contents:

Directory Purpose
proxygen/external/ Contains non-installed 3rd-party code proxygen depends on.
proxygen/lib/ Core networking abstractions.
proxygen/lib/http/ HTTP specific code.
proxygen/lib/services/ Connection management and server code.
proxygen/lib/utils/ Miscellaneous helper code.
proxygen/httpserver/ Contains code wrapping proxygen/lib/ for building simple C++ http servers. We recommend building on top of these APIs.

Architecture

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

When bytes are read off the wire, the HTTPCodec stored inside HTTPSession parses these into higher level objects and associates with it a transaction identifier. The codec then calls into HTTPSession which is responsible for maintaining the mapping between transaction identifier and HTTPTransaction objects. Each HTTP request/response pair has a separate HTTPTransaction object. Finally, HTTPTransaction forwards the call to a handler object which implements HTTPTransaction::Handler. The handler is responsible for implementing business logic for the request or response.

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

The same handler and transaction interfaces are used to both create requests and handle responses. The API is generic enough to allow both. HTTPSession is specialized slightly differently depending on whether you are using the connection to issue or respond to HTTP requests.

Core Proxygen Architecture

Moving into higher levels of abstraction, proxygen/httpserver has a simpler set of APIs and is the recommended way to interface with proxygen when acting as a server if you don't need the full control of the lower level abstractions.

The basic components here are HTTPServer, RequestHandlerFactory, and RequestHandler. An HTTPServer takes some configuration and is given a RequestHandlerFactory. Once the server is started, the installed RequestHandlerFactory spawns a RequestHandler for each HTTP request. RequestHandler is a simple interface users of the library implement. Subclasses of RequestHandler should use the inherited protected member ResponseHandler* downstream_ to send the response.

Using it

Proxygen is a library. After installing it, you can build your own C++ server. Try cding to the directory containing the echo server at proxygen/httpserver/samples/echo/. You can then build it with this one liner:

g++ -std=c++14 -o my_echo EchoServer.cpp EchoHandler.cpp -lproxygenhttpserver -lfolly -lglog -lgflags -pthread

After running ./my_echo, we can 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

Documentation

We use Doxygen for Proxygen's internal documentation. You can generate a copy of these docs by running doxygen Doxyfile from the project root. You'll want to look at html/namespaceproxygen.html to start. This will also generate folly documentation.

Contributing

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

Whitehat

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

proxygen open issues Ask a question     (View All Issues)
  • over 2 years Support for QUIC
  • over 2 years large post data process
  • over 2 years wangle lib not included
  • almost 3 years Install Problem similar to #25 which is closed
  • almost 3 years Build failed on Ubuntu 16.04
  • almost 3 years /usr/bin/ld: EchoHandler.o: undefined reference to symbol '_ZNSt3__18ios_base5clearEj'
  • almost 3 years Server & Client duplicate singleton registration of folly::Singleton proxygen::SharedWheelTimer
  • about 3 years Multipart form parser
  • about 3 years Does proxygen support Windows ?
  • over 3 years Add HTTP routing
  • over 3 years SPDYCodecTest.HeaderWithManyValues test fails on Ubuntu > 14
  • almost 4 years HAR export support
  • about 4 years Host header
  • over 4 years Mac OSX support incomplete
proxygen open pull requests (View All Pulls)
  • include gflags for declare statement and fix chain logic bug
  • Changes for OS X support
  • Install sudo for docker deploys
  • For Travis just build Docker image.
  • Cleanup Dockerfile: Use less commands.
  • Fix build/test with new location of gmock/gtest
  • Use the portable accessor from Folly to access flags in struct event.
  • Added lines to update package manager and commented out lines to inst…
  • Issue #124, include wangle lib
  • gtest-all.cc target breaks parallel builds (make -jN)
  • Conf websocket
  • PR154 add CentOS dependencies
  • Automatic ETag filter
  • Sample application combining Websocketpp and Proxygen
  • Changes to build this on Centos 6.7
  • Qcram prototype
  • Compression Simulator changes.
  • Return session idle time in actual milliseconds
proxygen questions on Stackoverflow (View All Questions)
  • proxygen throws System.NullReferenceException
  • How to send HTTP chunked response to emulate a video stream using Proxygen and Folly?
  • Problems running JNI4NET proxygen with xml config
proxygen list of languages used
Other projects in C++