Hello all, I spent today playing with beast. I had been watching Vinnie build this library on the cpp slack with keen interest. This review comes after spending a day building something with boost. I rewrote something I had written on top of ASIO to offer a http server and web sockets to use the v8 inspector protocol similar to what nodeJS offers but for an internal project. I tried to use the docs, and in dire circumstances use the examples. where possible and avoid reading the actual implementation code, so this review is mostly about API design/documentation (given its mission statement, this seems fair :D) - What is your evaluation of the design? With in an hour I had managed to go from a cursory understanding of beast through random interactions on the cpp slack, to a working threaded http server. I call this a win. I had no real problems here, having an understanding of boost::asio certainly put me in the right frame of mind. I loved the fact that it avoided the usual temptation of stringly typed status codes, header access etc. The Field access was a joy to work with knowing I would get a compiler error on incorrect access. It strikes the right balance between convenience and keeping a shallow API surface. Things that you are likely to want access to all the time, status code, path etc are available via helper methods. I did run into a few doc issues which I have outlined to vinnie off list. One is being tracked here [1] Another that i think could be useful. The docs here [2] could indicate that it will always include the leading "/" one of those small things that I always umm and ahh over when writing equality checks for items that uses strings for paths. I wanted to call out that having a websocket library included in the one library is a huge time saver. No having to worry about version miss-matches, dependency tracking etc. In my implementation the debug client requests a path using http GET. The server returns some information and then a upgrade request comes in. Being able to call accept(request) when i know i am expecting the upgrade and have it just work with out having to think about it was great! A huge -1 from me to splitting the libraries. - What is your evaluation of the implementation? I didn't look with much detail, the few times I had to debug some things and stepped into the code, it looked well structured, easy to follow and figure out where I went wrong. There seems to be a good usage of static_assert to help avoid situations where decorator_requests are expected over a request etc. - What is your evaluation of the documentation? As per above, I managed to get quite far just by reading the documentation. The places where I fell over and had to read examples was around getting data out of beast into standard types. I started to piece it together by reading the code(and having a mental shift that beast buffers are heavily based on asio buffers) I eventually just used the example here [3] I did reach for boost::asio::buffer_cast but couldn't get that to work. I did find the error of my ways in [4] this method would be super useful in beast it self! Which leads me to... One thing I am not sure, is there room in beast for more convenience methods here, I can see a lot of library authors having to repeat a lot of code to turn buffers -> string/ string streams etc. This could easily be provided as a utility out side of beast though, or via simple documentation in a FAQ to avoid having to reach for reading the implementation code. Another issue I hit was websockets and buffers and who owns draining etc. There is already a github issue for this [5] as well as a conversation on this mailing list. - What is your evaluation of the potential usefulness of the library? On a purely selfish level. It meets a few of my immediate needs! On a bigger level, the web is eating the world. Currently dealing with HTTP in C++ is harder than it should be for simple things like rest, oauth, or getting a simple server up and running quickly are harder than they should be. The only rest client I know of that supports oauth 2 is cpprestsdk by microsoft [6], this makes it much harder than it should be to talk to a growing list of services only available via rest/graphql via http. Beast has taken away the boring parts of doing all of that, so library authors can focus on writing solid web based libraries for the C++ ecosystem. Hopefully if this is accepted in to boost this will be the tipping point to more C++ http based libs! - Did you try to use the library? With which compiler(s)? Did you have any problems? I used the library with clang 4.0 and Apple LLVM version 8.0.0 (clang-800.0.42.1) Compiled with -std=c++14 No problems. - How much effort did you put into your evaluation? A glance? A quick reading? In-depth study? A fairly in-depth study of the api and the documentation. Along with building a library on top of it. A quick reading of the actual implementation details when having to debug problems. - Are you knowledgeable about the problem domain? Yes. I have worked on the web for a while, across a variety of languages and platforms. Have written more than 1 HTTP server and web socket server/clients on top of boost::asio (they seem to follow me through my career). Have worked on such web technologies such as blink/CEF/webkit. My one line summary: Beast should be ACCEPTED into Boost. Jared. [1] https://github.com/vinniefalco/Beast/issues/621 [2] http://vinniefalco.github.io/beast/beast/ref/beast__http__message/target.htm... [3] http://vinniefalco.github.io/beast/beast/using_http/buffer_oriented_serializ... . [4] https://github.com/vinniefalco/Beast/blob/develop/test/core/buffer_test.hpp#... [5] https://github.com/vinniefalco/Beast/issues/611 [6] https://github.com/Microsoft/cpprestsdk. On Sat, 1 Jul 2017 at 17:39 Michael Caisse via Boost <boost@lists.boost.org> wrote:
The formal review of Vinnie Falco’s Beast library will take place from July 1 through July 10, 2017.
Please consider participating in this review. The success of Boost is partially a result of the quality review process which is conducted by the community. You are part of the Boost community. I will be grateful to receive a review based on whatever level of effort or time you can devote.
Beast is a C++ header-only library serving as a foundation for writing interoperable networking libraries by providing low-level HTTP/1, WebSocket, and networking protocol vocabulary types and algorithms using the consistent asynchronous model of Boost.Asio.
Beast is designed for:
* Symmetry: Algorithms are role-agnostic; build clients, servers, or both. * Ease of Use: Boost.Asio users will immediately understand Beast. * Flexibility: Users make the important decisions such as buffer or thread management. * Performance: Build applications handling thousands of connections or more. * Basis for Further Abstraction: Components are well-suited for building upon.
A branch has been made for the review. You can find Beast for review at these links:
* Documentation : <http://vinniefalco.github.io/stage/beast/review/> * Source code : <https://github.com/vinniefalco/Beast/tree/review> * The FAQ answers real questions that come up :
< http://vinniefalco.github.io/stage/beast/review/beast/design_choices/faq.htm...
A lightning talk from CppCon 2016 introducing Beast can be found here: <https://www.youtube.com/watch?v=uJZgRcvPFwI>
Please provide in your review whatever information you think is valuable to understand your final choice of ACCEPT or REJECT including Beast as a Boost library. Please be explicit about your decision.
Some other questions you might want to consider answering:
- What is your evaluation of the design? - What is your evaluation of the implementation? - What is your evaluation of the documentation? - What is your evaluation of the potential usefulness of the library? - Did you try to use the library? With which compiler(s)? Did you have any problems? - How much effort did you put into your evaluation? A glance? A quick reading? In-depth study? - Are you knowledgeable about the problem domain?
More information about the Boost Formal Review Process can be found here: <http://www.boost.org/community/reviews.html>
Thank you for your effort in the Boost community.
Happy coding - michael
-- Michael Caisse Ciere Consulting ciere.com
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost