more small tutorial fixes (take 2)

[jab]

• Fix outdated "no HTTP library yet" comment
• Fix typo (s/mean time/meantime)

[codecov]

Codecov Report

Merging #489 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #489   +/-   ##
=======================================
  Coverage   99.26%   99.26%           
=======================================
  Files          89       89           
  Lines       10403    10403           
  Branches      718      718           
=======================================
  Hits        10327    10327           
  Misses         58       58           
  Partials       18       18

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 6e0b92b...83a7fc0. Read the comment docs.

[njsmith]

This is an extremely finicky and unimportant issue, but since it comes up a lot I guess it's still worth mentioning: despite what you may have heard, the basic "make a hyperlink please" syntax in ReST uses two trailing underscores. If you use just one trailing underscore, then ReST treats it as, I don't even know, defining a term or something, so if your document happens to have two links with the same text and different targets, ReST freaks out. To avoid all this nonsense, it's a good habit to use the double underscores everywhere. (See the other links in the docs for examples.)

[jab]

Good catch, thanks! Amended in 83a7fc0.

[jab]

I was thinking more about the "http is a more relevant example than echo" thing (as it definitely rang true for this new Trio user), and wondered whether an HTTP CONNECT proxy could provide a better example with still no need for an http library.

To verify this, I sketched one out in https://github.com/jab/trio_http_proxy/blob/master/trio_http_proxy.py and was delighted that (1) it didn't take too long for me to get working even though I'm new to Trio, and (2) it was even simpler to implement than I thought it would be (<60 SLOC). Go Trio!

Just wanted to share that in case adding such an example to the docs could be useful for other new Trio users. I'm not sure this should replace the echo server example, as this doesn't quite illustrate everything that the echo server example illustrates (e.g. having separate client and server, the flow control gotcha in the echo client, etc.), but on the other hand, this does demonstrate something else that's interesting, namely piping between streams, and best of all, at the end you can hook your browser up to it and see real live HTTPS sites loading through your proxy. I can see that being a lot more exciting to new users than the echo server, since you can immediately relate better to things that do something real and useful. (Sure, it doesn't proxy HTTP sites, but the web is increasingly dominated by HTTPS anyway, especially for more important stuff.) Maybe worth including this as a first example, with the echo server example second?

(Any feedback about my initial implementation would be much appreciated too -- hope I didn't do anything silly:)

Thanks for the great work on this project! Trio is 🔥🔥🔥

[jab]

@njsmith Happy to work up a PR integrating an example like this into the tutorial if that would be helpful, or maybe even just a quick line like the following?

For another example, check out how you can build an HTTP CONNECT proxy on top of Trio in under 60 lines of code.

[njsmith]

Oh, I missed your comment earlier, sorry! That's super neat. See also #472 (and I've made a note here: #472 (comment))

It's definitely too complicated to be the very first example, like the echo server is. In my talk I've been using a simple TCP proxy as an example, which is kind of in the same space but a bit simpler. In fact I think the simplicity of that TCP proxy is one of the strongest arguments for trio :-). But the version you'll see in those Jupyter notebooks is a bit clunky to set up, which makes it awkward for a tutorial -- combining the two ideas, maybe it would work to show a TCP proxy that redirects some local port to httpbin.org:80, so people can browse to http://localhost:12345 and see the remote host?

[jab]

Cool you've been collecting examples in #472 (hadn't seen that), and super cool to see your talk (hadn't seen that either) – live coding happy eyeballs in 40 lines was amazing! Reassuring to see that my HTTP CONNECT proxy example has the same basic structure as your TCP proxy example too. On that note, I think the TCP proxy example is great for its simplicity, so definitely worth including too, but even with the change to redirect to httpbin, I'm not sure the payoff comes close – like when I saw that I could point my browser through this tiny 60-line proxy I'd just written with Trio, and browsing any HTTPS site (including streaming YouTube) just worked, it felt like a super power. [1]
https://github.com/jab/trio_http_proxy#why
For whatever it's worth 😊

P.S. I saw 0.4 just came out, so I reworked the CONNECT example to use the new contextvar support instead of passing custom log functions around. Nice work on 0.4!

[1] Also +1 to the TCP proxy example being clunky to set up. I even hit nc: missing port with option -l when I tried running nc -l -p 12345 before I realized that my (macOS) flavor of nc wanted it spelled just nc -l 12345. OTOH, the setup for the CONNECT demo can be done with a GUI that users may even have used before.

[njsmith]

Okay, using the trio talk on youtube as the demo URL definitely wins an extra prize for slickness :-)