Re: [boost] [review][beast] Review of Beast starts today : July 1 - July 10

Subject: Re: [boost] [review][beast] Review of Beast starts today : July 1 - July 10
From: Jared Wyles (jared.wyles_at_[hidden])
Date: 2017-07-08 07:24:54

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.html
[3]
http://vinniefalco.github.io/beast/beast/using_http/buffer_oriented_serializing.html
.
[4]
https://github.com/vinniefalco/Beast/blob/develop/test/core/buffer_test.hpp#L23
[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_at_[hidden]>
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.html
> >
>
> 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