Document backends (HTTP and Downloads)

[ericphanson]

These probably should get a page in the docs. Follow up to #396 and #401

[nickrobinson251]

Somethings it might be good to document

• that these alternatives exist 😆
• when one might consider switching from HTTP (default) to Downloads (e.g. the HTTP backend is not safe for concurrent use, but Downloads should be)
• how to make that switch as a end user
• how to make that switch as the developer of a package, and any consequences for other packages that use AWS.jl (e.g. what happens if multiple packages set the backend? / how should packages set the backend in a safe way?)

[ericphanson]

Great list!

what happens if multiple packages set the backend?

If it's in the __init__, then whichever one loads last. If it's not in the __init__... I'm not really sure but maybe it won't even work since it'll just change the backend at precompile time (?).

how should packages set the backend in a safe way?

I think there is not a safe way to change the global backend from within library code, and libraries should set the backend per-request if they need a feature from a particular one, and otherwise should respect the default. I think "applications", i.e. leafs of the package dependency tree (so they themselves have no downstream packages, only upstream ones they depend on) can set the backend to whatever they would like.

---

Ideally, if one backend is strictly better (i.e. there's no reason to need another one), we should change the default here in AWS.jl. I think the DownloadsBackend is there theoretically (I don't think the HTTP.jl backend does anything the DownloadsBackend can't) but could possibly use some further testing in the wild first-- I've been using it and recommending it at Beacon without issues so far though, but mostly just with s3 and auth.

But if we somehow end up at a point where there are two backends and you might want one for one thing and another for another thing, then we can't really solve the issues by changing the default. I think the solution overall then is to just do it per-request when you need a particular one.

[omus]

I think there is not a safe way to change the global backend from within library code

For high-level API calls we can use #457 to allow for different libraries to specify what backend to use.

[IanButterworth]

I’ve just been trying and failing to work out how to switch to the Downloads backend. I was told once but can’t find where.

So addressing this issue would be appreciated! Even just posting how to here would help.

[IanButterworth]

Found a way in #516 (comment)

AWS.DEFAULT_BACKEND[] = AWS.DownloadsBackend()