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