Merge pull request #288 from RayforceDB/dev

v2.1.6

Author: singaraiona

.github/requirements-docs.txt

@@ -0,0 +1 @@
+mkdocs-material>=9.5

.github/workflows/pages.yml

@@ -14,7 +14,7 @@ on:
       - 'docs/**'
       - 'overrides/**'
       - 'mkdocs.yml'
-      - 'requirements-docs.txt'
+      - '.github/requirements-docs.txt'
       - '.github/workflows/pages.yml'
   workflow_dispatch:
 
@@ -36,9 +36,9 @@ jobs:
         with:
           python-version: '3.12'
           cache: pip
-          cache-dependency-path: requirements-docs.txt
+          cache-dependency-path: .github/requirements-docs.txt
       - name: Install MkDocs Material
-        run: pip install -r requirements-docs.txt
+        run: pip install -r .github/requirements-docs.txt
       - name: Build site (MkDocs)
         run: mkdocs build --strict
       - uses: actions/configure-pages@v4

docs/docs/language/control-flow.md

@@ -79,6 +79,20 @@ Recursive lambdas use `self` to refer to the enclosing function:
 
 If no error is raised, `try` returns the result of the body expression normally. Works inside lambdas compiled to bytecode.
 
+### Fallback value
+
+If the second argument is **not** a function, it is returned as-is as the fallback value on error (evaluated only when the body fails). Because lambdas do not capture closures, this is the only way to surface an outer binding from the failure branch:
+
+```lisp
+‣ (try (raise "boom") 0)
+0
+
+‣ ((fn [data] (try (raise "boom") data)) 123)
+123
+```
+
+A handler must accept the single error argument, so only a lambda or a unary builtin is *called* with the error; any other value (including a multi-argument builtin) is treated as a fallback value.
+
 ## Early Return: return
 
 `return` exits the innermost enclosing compiled lambda early with the given value:

docs/docs/language/functions.md

@@ -316,7 +316,7 @@ Cross-temporal comparisons are supported: dates, times, and timestamps are all c
 | `if` | variadic, special | Conditional (if/then/else) | `(if (> x 0) "pos" "neg")` |
 | `do` | variadic, special | Sequential execution, returns last | `(do (set x 1) (set y 2) (+ x y))` |
 | `fn` | variadic, special | Create lambda function | `(fn [x] (* x x))` |
-| `try` | binary, special | Error handling (expr handler) | `(try (/ 1 0) (fn [e] 0))` |
+| `try` | binary, special | Error handling (expr handler-or-fallback) | `(try (/ 1 0) (fn [e] 0))` |
 | `raise` | unary | Throw an error | `(raise "bad input")` |
 | `return` | variadic | Early return from compiled lambda (0 args → null) | `(return 42)` |
 | `quote` | variadic, special | Return argument unevaluated; a bare name becomes a literal symbol (`(quote x)` ≡ `'x`) | `(quote (+ 1 2))` → `(+ 1 2)` |

docs/docs/namespaces/ipc.md

@@ -12,22 +12,25 @@ Connect to a Rayforce server (`./rayforce -p <port>`) and exchange messages over
 
 | Function | Arity | Flags | Description |
 |---|---|---|---|
-| [`.ipc.open`](#ipc-open) | unary | restricted | Open a TCP connection; return an i64 handle. |
+| [`.ipc.open`](#ipc-open) | variadic | restricted | Open a TCP connection (optional connect timeout); return an i64 handle. |
 | [`.ipc.send`](#ipc-send) | binary | restricted | Send a message synchronously; return the server's result. |
 | [`.ipc.post`](#ipc-post) | binary | restricted | Send a message asynchronously (fire-and-forget); return the null object. |
 | [`.ipc.close`](#ipc-close) | unary | restricted | Close a connection handle. |
 | [`.ipc.handle`](#ipc-handle) | variadic | — | The current connection's handle inside a server-side hook; `-1` otherwise. |
 
 ## `.ipc.open` { #ipc-open }
 
-Signature: `(.ipc.open "host:port")` or `(.ipc.open "host:port:user:password")`.
+Signature: `(.ipc.open "host:port")` or `(.ipc.open "host:port:user:password")`, with an optional trailing connect timeout in milliseconds: `(.ipc.open "host:port" 2000)`.
 
 Returns: an `i64` handle. Negative handles never escape — errors are surfaced as Rayfall error objects:
 
-- `type` — argument is not a string.
-- `domain` — malformed address (missing port, port out of `(0, 65535]`, oversized host/user/password).
+- `type` — address argument is not a string, or the timeout argument is not an integer.
+- `rank` — called with fewer than 1 or more than 2 arguments.
+- `domain` — malformed address (missing port, port out of `(0, 65535]`, oversized host/user/password), or a negative timeout.
 - `access` — server requires auth and you didn't supply credentials, **or** the password is wrong.
-- `io` — connection refused / network error.
+- `io` — connection refused / network error, or `connection timed out` when the connect did not complete within the timeout.
+
+The optional timeout bounds **both** the TCP connect and the handshake I/O. A blocking `connect()` ignores socket send/receive timeouts, so without an explicit bound a dead or packet-filtered peer would otherwise hang for the operating-system default (often minutes). When omitted, a default budget of 5 seconds applies.
 
 The handshake exchanges a 2-byte `{wire_version, auth_flag}` greeting. A wire-version mismatch closes the connection before any payload is exchanged.
 
@@ -37,6 +40,9 @@ The handshake exchanges a 2-byte `{wire_version, auth_flag}` greeting. A wire-ve
 
 ;; With credentials (server started with -u or -U)
 (set h (.ipc.open "127.0.0.1:5000:admin:secret123"))
+
+;; Fail fast if the peer doesn't answer within 2 seconds
+(set h (.ipc.open "127.0.0.1:5000" 2000))
 ```
 
 ## `.ipc.send` { #ipc-send }

docs/docs/reference/all-functions.md

@@ -231,7 +231,7 @@ Special forms receive their arguments unevaluated. These are the core language p
 | `if` | variadic | special | Conditional: (if cond then else) | `(if (> x 0) "pos" "neg")` |
 | `do` | variadic | special | Sequential execution, returns last value | `(do (set x 1) (set y 2) (+ x y))` |
 | `fn` | variadic | special | Create lambda function | `(fn [x y] (+ x y))` |
-| `try` | binary | special | Error handling: (try expr handler-fn) | `(try (/ 1 0) (fn [e] 0))` |
+| `try` | binary | special | Error handling: (try expr handler-fn-or-fallback-value) | `(try (/ 1 0) (fn [e] 0))` |
 | `raise` | unary | — | Throw an error with message | `(raise "bad input")` |
 | `return` | unary | — | Early return from function body | `(return 42)` |
 | `quote` | variadic | special | Return argument unevaluated; a bare name yields a literal symbol (`(quote x)` ≡ `'x`) | `(quote (+ 1 2))` → `(+ 1 2)` |
@@ -530,7 +530,7 @@ TCP-based IPC for connecting to remote Rayforce instances. Uses binary serializa
 
 | Function | Type | Flags | Description | Example |
 |---|---|---|---|---|
-| `.ipc.open` | unary | restricted | Open TCP connection to host:port, returns handle | `(.ipc.open "localhost:5000")` |
+| `.ipc.open` | variadic | restricted | Open TCP connection to host:port (optional connect timeout in ms), returns handle | `(.ipc.open "localhost:5000" 2000)` |
 | `.ipc.close` | unary | restricted | Close an IPC connection handle | `(.ipc.close h)` |
 | `.ipc.send` | binary | restricted | Send a value over an IPC handle (sync request) | `(.ipc.send h "(sum (til 100))")` |
 | `.ipc.handle` | variadic | — | Current connection handle inside any `.ipc.on.*` hook, `-1` outside | `(.ipc.handle)` |

include/rayforce.h

@@ -647,7 +647,8 @@ ray_t* ray_fmt(ray_t* obj, int mode);
  * exchange; ray_ipc_send_async sends a fire-and-forget frame. */
 
 int64_t   ray_ipc_connect(const char* host, uint16_t port,
-                          const char* user, const char* password);
+                          const char* user, const char* password,
+                          int timeout_ms);
 void      ray_ipc_close(int64_t handle);
 ray_t*    ray_ipc_send(int64_t handle, ray_t* msg);
 ray_err_t ray_ipc_send_async(int64_t handle, ray_t* msg);

src/app/repl.c

@@ -573,7 +573,7 @@ ray_t* ray_repl_connect_fn(ray_t* host_port_str) {
      * and the connect-error-to-rayfall-error mapping; reusing it
      * keeps .repl.connect a one-line wrapper instead of a parallel
      * implementation that drifts. */
-    ray_t* opened = ray_hopen_fn(host_port_str);
+    ray_t* opened = ray_hopen_fn(&host_port_str, 1);
     if (!opened || RAY_IS_ERR(opened)) return opened;
     if (!ray_is_atom(opened) ||
         (opened->type != -RAY_I64 && opened->type != -RAY_I32)) {

src/core/ipc.c

@@ -339,10 +339,24 @@ static int hook_call_auth(ray_poll_t* poll, int64_t handle,
 static void send_response(ray_sock_t fd, ray_t* result)
 {
     int64_t ser_size = ray_serde_size(result);
-    if (ser_size <= 0) return;
+
+    /* A result we cannot serialize must never leave the client waiting on
+     * a reply that never arrives.  Substitute a serializable error so the
+     * caller observes a clean failure instead of a silent infinite hang
+     * (issue #285).  ray_error frames serialize, so the substitute always
+     * goes out unless even that fails — in which case there is nothing we
+     * can put on the wire and we drop as before. */
+    ray_t* fallback = NULL;
+    if (ser_size <= 0) {
+        fallback = ray_error("type", "result of type %s is not serializable over IPC",
+                             result ? ray_type_name(result->type) : "null");
+        result   = fallback;
+        ser_size = ray_serde_size(result);
+        if (ser_size <= 0) { if (fallback) ray_error_free(fallback); return; }
+    }
 
     uint8_t* payload = (uint8_t*)ray_sys_alloc((size_t)ser_size);
-    if (!payload) return;
+    if (!payload) { if (fallback) ray_error_free(fallback); return; }
     ray_ser_raw(payload, result);
 
     uint8_t* send_buf = NULL;
@@ -387,6 +401,7 @@ static void send_response(ray_sock_t fd, ray_t* result)
 
     ray_sys_free(send_buf);
     if (payload) ray_sys_free(payload);
+    if (fallback) ray_error_free(fallback);
 }
 
 /* Decompress (when flagged) + de-serialize one framed payload into an
@@ -501,6 +516,15 @@ static ray_t* eval_payload_core(uint8_t* payload, size_t payload_len,
             ray_release(msg);
         }
     }
+    /* A lazy result is an internal deferred-DAG representation that cannot
+     * be serialized — force it to a concrete value before it reaches the
+     * wire.  The direct ray_eval(msg) path (non-STR payloads, e.g. an
+     * expression list `(first v)`) returns lazy chains verbatim; the
+     * ray_eval_str path already materializes, so this is a no-op there.
+     * Without this, send_response cannot serialize the result and the
+     * client blocks forever waiting for a reply (issue #285). */
+    if (result && ray_is_lazy(result))
+        result = ray_lazy_materialize(result);  /* consumes the retain */
     return result ? result : RAY_NULL_OBJ;
 }
 
@@ -1401,16 +1425,20 @@ static int64_t conn_write_msg(ray_sock_t fd, ray_t* msg, uint8_t msgtype,
 }
 
 int64_t ray_ipc_connect(const char* host, uint16_t port,
-                         const char* user, const char* password)
+                         const char* user, const char* password,
+                         int timeout_ms)
 {
     /* The connection lives in the active poll's selector table — its
      * selector id IS the handle.  No poll, no handle namespace: refuse
      * up front rather than hand out an integer nothing can resolve. */
     ray_poll_t* poll = ipc_active_poll();
     if (!poll) return -1;
 
-    ray_sock_t fd = ray_sock_connect(host, port, 5000);
-    if (fd == RAY_INVALID_SOCK) return -1;
+    /* Default the connect/handshake budget to 5s when the caller gives
+     * no explicit timeout, matching the long-standing handshake timeout. */
+    int connect_to = timeout_ms > 0 ? timeout_ms : 5000;
+    ray_sock_t fd = ray_sock_connect(host, port, connect_to);
+    if (fd == RAY_INVALID_SOCK) return (errno == ETIMEDOUT) ? -5 : -1;
 
     uint8_t hs[2] = { RAY_SERDE_WIRE_VERSION, 0x00 };
     if (ray_sock_send(fd, hs, 2) < 0) {

src/core/ipc.h

@@ -114,8 +114,13 @@ int       ray_ipc_poll(ray_ipc_server_t* srv, int timeout_ms);
  * the connection's rx machinery while waiting, dispatching any
  * interleaved async/sync frames from the peer. */
 
+/* timeout_ms > 0 bounds the TCP connect and the handshake I/O; <= 0 uses
+ * the default budget.  Returns the handle (>= 0) or a negative code:
+ * -1 refused/error, -2 auth required, -3 auth failed, -4 wire mismatch,
+ * -5 connect timed out. */
 int64_t   ray_ipc_connect(const char* host, uint16_t port,
-                           const char* user, const char* password);
+                           const char* user, const char* password,
+                           int timeout_ms);
 void      ray_ipc_close(int64_t handle);
 ray_t*    ray_ipc_send(int64_t handle, ray_t* msg);
 ray_err_t ray_ipc_send_async(int64_t handle, ray_t* msg);