Restore HTTP.Exceptions as a deprecating compat shim + migration note (#1315)

Re-add HTTP.Exceptions as a thin deprecated submodule forwarding HTTPError,
StatusError, ConnectError and TimeoutError to the canonical top-level names via
Base.@deprecate_binding (as the existing escape -> escapeuri), so downstream
`catch ... isa HTTP.Exceptions.StatusError` keeps working with a deprecation
warning. RequestError, @Try and current_exceptions_to_string are not reinstated;
the migration guide documents them (RequestError has no drop-in -- the underlying
exception propagates and isrecoverable classifies it).

Closes #1314.

Author: mathieu17g

docs/src/guides/migration-1x.md

@@ -359,6 +359,55 @@ Use the timeout that matches your intent:
 Timeout failures are reported as `HTTP.HTTPTimeoutError`, an alias for
 `HTTP.TimeoutError`.
 
+## Exceptions
+
+In 1.x the client exception types lived in the `HTTP.Exceptions` submodule and were
+re-exported to the top level. 2.x keeps the types at the top level — `HTTP.StatusError`,
+`HTTP.ConnectError`, `HTTP.TimeoutError`, and their `HTTP.HTTPError` supertype — and
+`HTTP.Exceptions` is now a thin deprecated shim. Prefer the top-level names.
+
+Before:
+
+```julia
+catch e
+    e isa HTTP.Exceptions.StatusError && @info "status" e.status
+end
+```
+
+After:
+
+```julia
+catch e
+    e isa HTTP.StatusError && @info "status" e.status
+end
+```
+
+`HTTP.Exceptions.StatusError`, `ConnectError`, `TimeoutError`, and `HTTPError` still
+resolve — forwarding to the top-level names, with a deprecation warning under
+`--depwarn=yes`. The 1.x `@try` macro and `current_exceptions_to_string` helper were
+internal and are removed with no replacement.
+
+`HTTP.RequestError` is also gone. 1.x wrapped request-path failures in a `RequestError`
+(fields `.request`/`.error`); 2.x lets the underlying transport or protocol exception
+propagate directly, and exposes `HTTP.isrecoverable` to classify whether a failure is a
+transient one that is safe to retry.
+
+Before:
+
+```julia
+catch e
+    e isa HTTP.Exceptions.RequestError && @warn "request failed" e.error
+end
+```
+
+After:
+
+```julia
+catch e
+    HTTP.isrecoverable(e) || rethrow()   # otherwise it is a transient transport failure
+end
+```
+
 ## TLS, Sockets, and Proxies
 
 The old `sslconfig` and `socket_type_tls` extension points are retained for
@@ -641,6 +690,7 @@ Treat these as temporary migration aids. New code should use the documented
 - Prefer keyword constructors for `Request` and `Response`.
 - Replace `pool` usage with a long-lived `HTTP.Client`.
 - Replace `readtimeout` with the precise timeout keyword you need.
+- Replace `HTTP.Exceptions.StatusError` & friends with the top-level `HTTP.StatusError`; `HTTP.RequestError` is gone — catch the underlying exception or use `HTTP.isrecoverable`.
 - Replace `HTTP.download` with `Downloads.download` or an explicit
   `HTTP.request(...; response_stream = io)` file stream.
 - Move WebSocket code to `HTTP.WebSockets`.

src/HTTP.jl

@@ -87,6 +87,21 @@ include("http_websockets.jl")
     ))
 end
 
+# Backward-compatibility shim for the 1.x `HTTP.Exceptions` submodule. In 1.x these
+# exception types were defined in `HTTP.Exceptions` and re-exported to the top level;
+# 2.x keeps them at the top level (`HTTP.StatusError` etc.) but dropped the submodule,
+# breaking downstream code that reached in via `HTTP.Exceptions.StatusError`. Re-add a
+# thin deprecated `Exceptions` module forwarding to the canonical names — see #1314.
+# (`@try`, `current_exceptions_to_string` and `RequestError` are not reinstated; see the
+# migration guide.)
+module Exceptions
+    import ..HTTP
+    Base.@deprecate_binding HTTPError    HTTP.HTTPError    false
+    Base.@deprecate_binding StatusError  HTTP.StatusError  false
+    Base.@deprecate_binding ConnectError HTTP.ConnectError false
+    Base.@deprecate_binding TimeoutError HTTP.TimeoutError false
+end
+
 if ccall(:jl_generating_output, Cint, ()) == 1
     include("precompile.jl")
 end