[Issue 9737] std.net.curl and SSL - documentation missing

[d-bugmail at puremagic.com]

https://d.puremagic.com/issues/show_bug.cgi?id=9737



--- Comment #6 from Manu <turkeyman at gmail.com> 2013-11-12 20:00:52 PST ---
(In reply to comment #5)
> I agree that the line of documentation added is not a 'how does https' work, or
> even a 'what does libcurl need to have done to make https work'.  However, it
> is a reasonable description of what that api does.

But this bug doesn't say "document this API", it says "std.net.curl and SSL -
documentation missing", which is still true, so this bug is still open for my
money.

> This issue boils down, I believe, to be essentially, libcurl was incompletely
> setup on the reporters box and a faq entry would be handy.  A properly
> installed libcurl  includes the cert bundle that libcurl uses automatically by
> default, allows https urls to 'just work'.  For non-windows platforms, this is
> done by the platforms' packaging of libcurl.  For the windows platform, it's
> libcurl doesn't have one by default and the urls in the original report address
> the situation pretty well.
> 
> So, some additional documentation near the top of the std.net.curl (and
> etc.c.curl) would be useful.  A few pointers off to the those curl doc pages,
> maybe one or two good https background docs.  However, I do not believe that
> inside the phobos docs is a reasonable place to put documentation about the
> general topic of how https works and even more generally how encryption works.

I think an important point is, I didn't even realise that *HTTPS* specifically
didn't work, I was just annoyed that a seemingly trivial API [get(url)] didn't
just work. After I worked out that it was HTTPS related, there was no mention
of HTTPS anywhere in the docs, or examples, or that it required special
treatment.

What you say is fine, it's not the place for an intro to SSL/encryption, but it
needs to be made clear that HTTPS is not trivial, and requires special
handling, and the error message needs to be improved so programmer's aren't
left wondering why it didn't work.


That said, I think there's a secondary 'bug' here, that is, std.net.curl is
broken on some platforms out of the box.
We're talking about a lib under 'std' here. If it's part of phobos, then it
shouldn't depend on anything that's not distributed with phobos.

Consider any other modern language, python, java, C#, PHP, Ruby... if I make a
HTTP request, it works. I think that's a reasonable end-user expectation.
Basically all websites are HTTPS these days, it needs to just work too.

If it requires ancilliary files, I'd say it's the DMD/GDC/LDC distributions
responsibility to make sure these api's do just work.
Documenting that it doesn't work (but you can make it work by following these
simple steps) is isn't acceptable.

Why isn't the file which just seems to be full of (standard?) magic keys
embedded in curl or phobos?

-- 
Configure issuemail: https://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------