SSE Support and Minor Cleanups (#66)

* Initial commit of SSE support

* SSE documentation

* minor fixes after review

* sse documentation

* Update version to 5.11.0

Author: bpbecker

.gitignore

@@ -1,3 +1,5 @@
 *.dlf
 *.rng*
-site/
+site/
+.claude/
+.devcontainer/

docs/sse-settings.md

@@ -0,0 +1,27 @@
+SSE settings control whether an `HttpCommand` instance will accept Server-Sent Events (SSEs).
+
+## Instance settings
+
+### `EnableSSE`
+
+|--|--|
+|Description|A Boolean that enables `HttpCommand` to process Server-Sent events.<ul><li>`1` = process SSEs</li><li>`0` = do not process SSEs</li></ul>|
+|Default|`0`|
+|Example(s)|`h.EnableSSE←1`|
+|Details|If `EnableSSE` is `0` and `HttpCommand` receives an SSE response from the host, indicated by a `content-type` header of `text/event-stream`, `HttpCommand` will terminate with `msg` of "Server responded with SSE, but EnableSSE=0"|
+
+### `ParseSSE`
+
+|--|--|
+|Description|A Boolean the indicates whether to process received SSE event messages into a more convenient namespace format.  Valid values are:<ul><li>`1` (the default) - parse into a namespace See [Handling SSE Event Messages](sse.md#handling-sse-event-messages).</li><li>`0` - do not parse, just return the raw event message</li></ul>|
+|Default|`1`|
+|Example(s)|`h.ParseSSE←0 ⍝ don't parse, just use raw event message`|
+|Details|If using `ParseSSE←0`, see [Parsing an event stream](https://html.spec.whatwg.org/multipage/server-sent-events.html#parsing-an-event-stream).|
+
+### `OnSSEfn`
+
+|--|--|
+|Description|`OnSSEfn` is the name of the function that you write that will be called when `HttpCommand` receives an SSE event message. The function should be dyadic and not return a result. The left argument is a reference to the `HttpCommand` result namespace. The right argument is either the raw SSE event message (if `ParseSSE←0`) or a namespace containing the parsed SSE event message (if `ParseSSE←1').
+|Default|`''`|
+|Example(s)|The following assumes that `ParseSSE←1`.<br/><pre style="font-family:APL;">onSSE←{'done'≡⍵.event: ⍺.Close ⍝ close the listener on a "done" event<br/>       ⎕←⍵.(event id) ⍝  otherwise display the event name and id}<br/>r.OnSSEfn←'onSSE'</pre>|
+|Details|If `OnSSEfn` is not specified, `HttpCommand` will display the SSE event message to the session.|

docs/sse.md

@@ -0,0 +1,75 @@
+Server-Sent Events (SSE) is a web technology that enables a server to push real-time updates to `HttpCommand`. Unlike WebSockets, which provide full-duplex communication, SSE is unidirectional — data flows only from server to client. `HttpCommand` initiates the connection with a standard HTTP request, and the server responds with a text/event-stream content type, keeping the connection open and sending data as a stream of newline-delimited messages. Each message can include fields such as data, event, id, and retry. SSE is particularly well-suited for use cases like live feeds, log streaming, and AI chat completions, where the server needs to continuously deliver updates without the client repeatedly polling.
+
+## Basic steps to use SSE
+
+* Write a dyadic, non-result-returning function to process the event messages from the server. We'll call this function the "SSE handler". 
+    * The right argument is the event payload.
+    * The left argument is a reference to the `HttpCommand` result namespace.
+    * If you do not write an SSE handler, the event message will be displayed to the APL session.
+* Create an instance of `HttpCommand`. For example: `h←HttpCommand.New ''`
+* Set `URL` to the address of the host server.
+* Set `EnableSSE` to `1`.
+* Set `OnSSEfn` to the name of the function you wrote.
+* If you do **not** want `HttpCommand` to parse the event messages into a namespace format, set `ParseSSE` to `0`. 
+* Run the `HttpCommand` instance, saving the reference to the result namespace. For example: `r←h.Run`<br/>This will start a listener on a separate thread.
+* Every time an event message is received, `HttpCommand` with pass either:
+    * If `ParseSSE` is `0`, the unmodified event message is passed as the right argument to the SSE handler.
+    * If `ParseSSE` is `1`, the a namespace containing the parsed event message is passed as the right argument to the SSE handler.
+* To stop the listener you can either hit interrupt or use the `Close` function in the result namespace. For example: `r.Close`.
+* You can also append the raw SSE event messages to a file by specifying [`OutFile`](operational-settings.md#outfile) and optionally [`MaxPayloadSize`](operational-settings.md#maxpayloadsize). If you specify `MaxPayloadSize`, the listener will quit when appending the current event message would exceed `MaxPayloadsize`.  
+
+## Handling SSE Event Messages
+When the listener receives an SSE event message it will:
+
+* If `OutFile` is specified, append the raw event message to the file specified by `OutFile`
+* If `ParseSSE` is `1` (the default), the event message is parsed based on the [SSE specification](https://html.spec.whatwg.org/multipage/server-sent-events.html#event-stream-interpretation) into a namespace format that's more useful in an APL environment. The namespace contains:
+    * `event` - the event name, or `'message'` if `event:` was not specified in the event message
+    * `data` - a vector of character vectors, one per occurrence of `data:` in the event message
+    * `id` - the `id:` of the event message or `''` if `id:` was not specified
+    * `retry` - if specified in the event message, the reconnection time in milliseconds. Note that the current architecture is not able to do anything with `retry`.
+* If you have specified `OnSSEfn`, it is called passing:
+    * a reference to the `HttpCommand` result namespace as its left argument
+    * as its right argument - the namespace described above if `ParseSSE←1` or the raw event message if `ParseSSE←0`
+* If you have not specified `OnSSEfn` the event message is displayed in the session.
+
+To stop the listener you can either call `r.Close` or generate an interrupt.
+
+## `HttpCommand` Result Namespace Modifications
+If you're using SSE, the `HttpCommand` result namespace has some additional elements:
+
+* `SSEThread` is the thread on which the listener is running
+* `Close` is a function to terminate the listener
+* `CloseSSE` is a Boolean which the listener checks for whether to terminate or not. The `Close` function sets `CloseSSE←1`
+* Additionally, the display format of the result namespace is updated whenever `msg`, `rc`, `HttpStatus`, or `HttpMessage` are updated.
+
+## Example
+<pre><code>      h←HttpCommand.New (
+      URL:'https://echo.websocket.org/.sse'
+      )
+      h.Run
+[rc: ¯1 | msg: Server responded with SSE, but EnableSSE=0 | HTTP Status: 200 "OK" | ≢Data: 0]
+</code></pre>
+Duh! Need to set `EnableSSE←1`
+<pre><code>onSSE←{
+       ⍝ ⍺ - reference to HttpCommand result namespace
+       ⍝ ⍵ - SSE payload              
+         '10'≡⍵.id: ⍺.Close ⍝ close listener when we get to id='10'
+         ⍵.(event id)       ⍝ otherwise display the event and id    
+       }                    
+      
+      h←HttpCommand.New (
+      URL:'https://echo.websocket.org/.sse'
+      EnableSSE:1
+      OnSSEfn:'onSSE'
+      )
+      r←h.Run
+ server  1
+ request  2
+ time  3
+ time  4
+ time  5
+ time  6
+ time  7
+ time  8
+ time  9
+</code></pre>

mkdocs.yml

@@ -16,6 +16,7 @@ nav:
         - 'Operational Settings': 'operational-settings.md' # complete
         - 'Conga-related Settings': 'conga-settings.md'     # complete
         - 'Proxy-related Settings': 'proxy-settings.md'     # complete
+        - 'SSE-related Settings': 'sse-settings.md'         
       - 'Shared Methods':
         - 'Shortcut Methods': 'shortcut-methods.md' # complete
         - 'Encode/Decode Methods': 'encode-methods.md' # complete
@@ -30,6 +31,7 @@ nav:
       - 'Request Content Types' : 'content-types.md'
       - 'HttpCommand and Conga' : 'conga.md' # complete
       - 'Secure Communications' : 'secure.md' # complete
+      - 'Using Server-Sent Events (SSE)' : 'sse.md' # complete
       - 'Using a Proxy Server': 'proxy.md' 
       - 'Integrating HttpCommand' : 'integrating.md' # complete
     - About: