-end)</code></pre><p>The callback can be <code>f(event)</code> or <code>f(stream, event)</code>. The two-argument form allows cancelling the request by calling <code>close(stream)</code> (for example, in response to a specific event).</p><p>Each callback receives a <code>SSEEvent</code> with the following fields:</p><ul><li><code>data::String</code>: newline-joined <code>data:</code> payload for the event (with the trailing newline removed).</li><li><code>event::Union{Nothing,String}</code>: the most recent <code>event:</code> field, or <code>nothing</code> when not provided (equivalent to the default <code>"message"</code> type).</li><li><code>id::Union{Nothing,String}</code>: the last <code>id:</code> value observed, automatically persisted between events per the SSE specification.</li><li><code>retry::Union{Nothing,Int}</code>: the last <code>retry:</code> directive in milliseconds, propagated to subsequent events until another <code>retry:</code> value is parsed.</li><li><code>fields::Dict{String,String}</code>: newline-joined string values for every field encountered since the previous event, including custom non-standard fields.</li></ul><p>Because HTTP.jl streams the response directly to the callback, the returned <code>HTTP.Response</code> will always have <code>response.body === HTTP.nobody</code>. The <code>sse_callback</code> keyword cannot be combined with <code>response_stream</code> or a custom <code>iofunction</code>, and parsing errors raise <code>HTTP.SSEError</code>. Compressed streams are supported automatically unless <code>decompress=false</code> is explicitly set.</p><p>For a full end-to-end example, see <a href="https://github.com/JuliaWeb/HTTP.jl/blob/master/docs/examples/server_sent_events.jl"><code>docs/examples/server_sent_events.jl</code></a>.</p><h3 id="Download"><a class="docs-heading-anchor" href="#Download">Download</a><a id="Download-1"></a><a class="docs-heading-anchor-permalink" href="#Download" title="Permalink"></a></h3><p>A <a href="@ref"><code>download</code></a> function is provided for similar functionality to <code>Downloads.download</code>.</p><h2 id="Client-side-Middleware-(Layers)"><a class="docs-heading-anchor" href="#Client-side-Middleware-(Layers)">Client-side Middleware (Layers)</a><a id="Client-side-Middleware-(Layers)-1"></a><a class="docs-heading-anchor-permalink" href="#Client-side-Middleware-(Layers)" title="Permalink"></a></h2><p>An <code>HTTP.Layer</code> is an abstract type to represent a client-side middleware. A layer is any function of the form <code>f(::Handler) -> Handler</code>, where <a href="@ref"><code>Handler</code></a> is a function of the form <code>f(::Request) -> Response</code>. Note that this <code>Handler</code> definition is the same from the server-side documentation. It may also be apparent that a <code>Layer</code> is the same as the <a href="@ref"><code>Middleware</code></a> interface from server-side, which is true, but we define <code>Layer</code> to clarify the client-side distinction and its unique usage.</p><p>Creating custom layers can be a convenient way to "enhance" the <code>HTTP.request</code> process with custom functionality. It might be a layer that computes a special authorization header, or modifies the body in some way, or treats the response specially. Oftentimes, layers are application or domain-specific, where certain domain knowledge can be used to improve or simplify the request process. Layers can also be used to enforce the usage of certain keyword arguments if desired.</p><p>Custom layers can be deployed in one of two ways:</p><ul><li><a href="../reference/#HTTP.@client"><code>HTTP.@client</code></a>: Create a custom "client" with shorthand verb definitions, but which include custom layers; only these new verb methods will use the custom layers.</li><li><a href="../reference/#HTTP.pushlayer!"><code>HTTP.pushlayer!</code></a>/<a href="../reference/#HTTP.poplayer!"><code>HTTP.poplayer!</code></a>: Allows globally adding and removing layers from the default HTTP.jl layer stack; <em>all</em> http requests will then use the custom layers</li></ul><h3 id="Quick-Examples"><a class="docs-heading-anchor" href="#Quick-Examples">Quick Examples</a><a id="Quick-Examples-1"></a><a class="docs-heading-anchor-permalink" href="#Quick-Examples" title="Permalink"></a></h3><pre><code class="language-julia hljs">module Auth
0 commit comments