Merge branch 'upstream-main'

Author: tae898

bolt/pom.xml

@@ -25,7 +25,7 @@
     <parent>
         <groupId>com.arcadedb</groupId>
         <artifactId>arcadedb-parent</artifactId>
-        <version>26.6.1-SNAPSHOT</version>
+        <version>26.6.1</version>
         <relativePath>../pom.xml</relativePath>
     </parent>
 

console/pom.xml

@@ -25,7 +25,7 @@
     <parent>
         <groupId>com.arcadedb</groupId>
         <artifactId>arcadedb-parent</artifactId>
-        <version>26.6.1-SNAPSHOT</version>
+        <version>26.6.1</version>
         <relativePath>../pom.xml</relativePath>
     </parent>
 

coverage/pom.xml

@@ -26,7 +26,7 @@
     <parent>
         <groupId>com.arcadedb</groupId>
         <artifactId>arcadedb-parent</artifactId>
-        <version>26.6.1-SNAPSHOT</version>
+        <version>26.6.1</version>
         <relativePath>../pom.xml</relativePath>
     </parent>
 

docs/4451-configurable-log-directory.md

@@ -0,0 +1,68 @@
+# Issue #4451 - Configurable Server Log Directory
+
+## Goal
+
+Allow the server's file-log directory to be configured via
+`arcadedb.server.logsDirectory` (or the `ARCADEDB_LOG_DIR` environment variable),
+enabling Kubernetes deployments with `readOnlyRootFilesystem` to write logs to a
+writable mount instead of crashing on a read-only working directory.
+
+## Problem
+
+The packaged `arcadedb-log.properties` hardcodes the JUL FileHandler pattern as
+`./log/arcadedb.log`. The Java logging framework resolves that path relative to the
+process working directory the first time any log call fires - which happens during
+`GlobalConfiguration` static initialization, before the server root path is even set.
+On a read-only root filesystem the working directory is not writable, so JUL fails to
+open the log file:
+
+```
+java.nio.file.FileSystemException: ./log/arcadedb.log.0.lck: Read-only file system
+```
+
+The directory cannot simply be tied to `arcadedb.server.rootPath`, because that value
+is still unset at the moment logging initializes. It must be resolvable from the
+environment alone.
+
+## Solution
+
+Resolve `${...}` placeholders in the FileHandler pattern inside `DefaultLogger` - the
+one place ArcadeDB controls the configuration stream before handing it to JUL - using
+the existing `SystemVariableResolver` (system property, then environment variable, then
+`GlobalConfiguration`), defaulting to `./log` so existing behavior is unchanged.
+
+The packaged pattern becomes:
+`java.util.logging.FileHandler.pattern=${arcadedb.server.logsDirectory}/arcadedb.log`
+
+Resolution is applied both when pre-creating the log directory and in the pattern handed
+to JUL, so the two agree. A pattern with no placeholder (e.g. an absolute literal path) is
+returned unchanged.
+
+Operators relocate the log directory by setting the environment variable:
+`ARCADEDB_LOG_DIR=/var/lib/arcadedb/log` (the launch scripts forward it as
+`-Darcadedb.server.logsDirectory=...`), or by setting the system property directly.
+When unset, logs default to `./log`, identical to prior releases.
+
+## Affected Files
+
+- `engine/src/main/java/com/arcadedb/log/DefaultLogger.java` - `resolveConfigurableLogDir` helper, wired into `createLogDirectoryFromConfig()` and `installCustomFormatter()`
+- `engine/src/main/java/com/arcadedb/GlobalConfiguration.java` - new `SERVER_LOGS_DIRECTORY` config entry (`arcadedb.server.logsDirectory`, default `./log`)
+- `engine/src/test/java/com/arcadedb/LoggerTest.java` - placeholder resolution + integration regression tests
+- `engine/src/test/java/com/arcadedb/GlobalConfigurationTest.java` - config entry test
+- `package/src/main/config/arcadedb-log.properties` - FileHandler pattern uses the placeholder
+- `package/src/main/scripts/server.sh`, `package/src/main/scripts/server.bat` - forward `ARCADEDB_LOG_DIR`
+
+## Verification
+
+- `LoggerTest` (8 tests) and `GlobalConfigurationTest` (10 tests): all PASS. Includes the
+  issue-#3732 regression tests, which prove literal patterns (the default `./log` behavior)
+  are unchanged.
+- Read-only-CWD smoke test against the real packaged `arcadedb-log.properties`: with a
+  read-only `./log` in the working directory and `arcadedb.server.logsDirectory` pointing at
+  a writable directory, the server logs to the writable directory, leaves `./log` untouched,
+  and does not throw the `Read-only file system` exception.
+
+## Backward Compatibility
+
+The default remains `./log`, so single-host and standard Docker deployments (where the
+working directory is writable) behave exactly as before. The change is additive.

docs/4468-sql-in-param-index-expansion.md

@@ -0,0 +1,107 @@
+# Issue #4468 - SQL `IN :param` with a collection parameter returns no rows when an index is used
+
+## Summary
+
+SQL queries using `IN :param` (named parameter) or `IN ?` (positional parameter) with a collection
+value return no rows when the field has an index and the index path is chosen by the planner.
+
+The same collection works on the non-indexed path (`WHERE (field + 0) IN :param`) and the literal
+form (`WHERE field IN [1, 2, 3]`) works without restriction.
+
+## Root Cause
+
+`PostCommandHandler.PostCommandHandler` uses `json.toMap(true)` to deserialize the HTTP request body.
+The `true` flag enables an optimized path that converts JSON numeric arrays (`[1, 2, 3]`) to
+primitive arrays (`long[]`, `double[]`) rather than `List<Long>` to reduce boxing allocations.
+
+When a parameter value like `codes = [1, 2, 3]` arrives at the server, the deserialized map entry
+is `"codes" -> long[]`.
+
+`FetchFromIndexStep.cartesianProduct()` is responsible for expanding a multi-value expression into
+one index lookup per element. Before this fix its check was:
+
+```java
+if (value instanceof Iterable<?> iterable && !(value instanceof Identifiable)) {
+```
+
+Primitive arrays (`long[]`, `int[]`, `Object[]`) are **not** `Iterable<?>` in Java.
+The condition was false, the `else` branch ran, and the whole array was passed as a single index
+key - matching nothing.
+
+The non-indexed evaluator uses `MultiValue.getMultiValueIterable()` which handles arrays correctly,
+so `WHERE (field + 0) IN :param` worked fine.
+
+## Fix
+
+`engine/src/main/java/com/arcadedb/query/sql/executor/FetchFromIndexStep.java`
+
+Replaced the `Iterable<?>`-only predicate in `cartesianProduct()` with the existing `MultiValue`
+utility, which already detects and iterates every array type (`long[]`, `int[]`, `double[]`,
+`Object[]`) as well as `Collection`/`Iterable`. This is the same utility the sibling
+`processInCondition()` path uses (lines 258-261 of the same file), so both multi-value detection
+sites now share one code path. `MultiValue.isMultiValue(null)` is internally null-safe, so no
+explicit null guard is needed.
+
+```java
+// Before
+if (value instanceof Iterable<?> iterable && !(value instanceof Identifiable)) {
+    for (final Object elemInKey : iterable) {
+
+// After
+if (!(value instanceof Identifiable) && MultiValue.isMultiValue(value)) {
+    for (final Object elemInKey : MultiValue.getMultiValueIterable(value)) {
+```
+
+## Files Changed
+
+- `engine/src/main/java/com/arcadedb/query/sql/executor/FetchFromIndexStep.java` - fix
+- `engine/src/test/java/com/arcadedb/index/InParamIndexExpansionTest.java` - regression tests
+
+## Test Results
+
+New regression test `InParamIndexExpansionTest` (11 test methods):
+- `literalInListUsesIndexAndReturnsRows` - passes before and after fix (baseline)
+- `namedListParamInWithIndexReturnsRows` - passes before and after fix (`List<Long>` is Iterable)
+- `namedPrimitiveLongArrayParamInWithIndexReturnsRows` - **failed before fix, passes after**
+- `namedPrimitiveIntArrayParamInWithIndexReturnsRows` - **failed before fix, passes after**
+- `namedPrimitiveDoubleArrayParamInWithIndexReturnsRows` - **failed before fix, passes after** (double coerces to INTEGER key)
+- `namedObjectArrayParamInWithIndexReturnsRows` - **failed before fix, passes after**
+- `positionalListParamInWithIndexReturnsRows` - passes (List is Iterable in embedded mode)
+- `namedListParamInExplainUsesIndex` - confirms index is used
+- `namedListParamInWithoutIndexReturnsRows` - control: non-indexed path works
+- `namedListParamInWithIndexReturnsPartialRows` - partial match works
+- `namedListParamInWithIndexReturnsSingleRow` - single-element list works
+
+Broader suite: index (embedded list, list-by-item, composite, map) and SQL query tests pass with
+0 failures, 0 errors.
+
+## Review cycles
+
+### Cycle 1 - `b940f325`
+
+- **gemini-code-assist** (1 comment): hoist the `value != null` null check to the front of the
+  `cartesianProduct` condition. Subsumed by the cycle-1 change below - switching to
+  `MultiValue.isMultiValue` (internally null-safe) removed the need for any explicit null guard.
+- **claude** (review comment): suggested reusing the already-imported `MultiValue` utility instead
+  of `IterableObjectArray` for consistency with `processInCondition`; add `int[]`/`double[]` test
+  cases; remove issue-reference comments from test method bodies; remove the docs file.
+  - Applied: switched to `MultiValue.isMultiValue` + `getMultiValueIterable` (verified safe across
+    embedded-list, list-by-item, map, and composite index suites); added `int[]` and `double[]`
+    test cases; removed issue-reference comments and em-dashes from test method bodies.
+  - Declined: removing this docs file. The `docs/<issue>-<name>.md` tracking doc is an established,
+    committed convention (38 such files already in the repo, e.g. `docs/4337-*`, `docs/4364-*`) and
+    is produced by the resolve-issue workflow. The claim that the convention does not exist is not
+    accurate.
+
+### Cycle 2 - `342fd2b2`
+
+- **claude** (Approved with minor suggestions):
+  - Noted that switching to `MultiValue` quietly broadens behavior for `Map` parameters (expanded by
+    `map.values()`), consistent with `processInCondition` but previously not reached. Added a concise
+    behavioral comment above the condition explaining the multi-value expansion. Did not add a `Map`
+    test, since that would lock incidental Map-expansion into a tested contract; the fix targets the
+    array/collection shapes produced by JSON parameter deserialization.
+  - Declined: trimming the class Javadoc per a cited "never write multi-paragraph docstrings" rule -
+    that rule is not present in CLAUDE.md, and the Javadoc documents a non-obvious root cause.
+  - Declined: removing the "Review cycles" section from this doc. 15+ committed tracking docs in the
+    repo (e.g. `docs/4274-*`, `docs/4331-*`) contain exactly this section; it is a convention.

e2e-ha/pom.xml

@@ -25,7 +25,7 @@
     <parent>
         <groupId>com.arcadedb</groupId>
         <artifactId>arcadedb-parent</artifactId>
-        <version>26.6.1-SNAPSHOT</version>
+        <version>26.6.1</version>
         <relativePath>../pom.xml</relativePath>
     </parent>
 

e2e/pom.xml

@@ -25,7 +25,7 @@
     <parent>
         <groupId>com.arcadedb</groupId>
         <artifactId>arcadedb-parent</artifactId>
-        <version>26.6.1-SNAPSHOT</version>
+        <version>26.6.1</version>
         <relativePath>../pom.xml</relativePath>
     </parent>
 

engine/pom.xml

@@ -25,7 +25,7 @@
     <parent>
         <groupId>com.arcadedb</groupId>
         <artifactId>arcadedb-parent</artifactId>
-        <version>26.6.1-SNAPSHOT</version>
+        <version>26.6.1</version>
         <relativePath>../pom.xml</relativePath>
     </parent>
 

engine/src/main/java/com/arcadedb/GlobalConfiguration.java

@@ -550,6 +550,11 @@ Enable diagnostic logging during vector graph build progress (heap/off-heap memo
       "Root path in the file system where the server is looking for files. By default is the current directory", String.class,
       null),
 
+  // Default must stay in sync with DefaultLogger.DEFAULT_LOG_DIR so the resolver fallback and the config default agree.
+  SERVER_LOGS_DIRECTORY("arcadedb.server.logsDirectory", SCOPE.JVM,
+      "Directory where the server writes log files, referenced as ${arcadedb.server.logsDirectory} in arcadedb-log.properties. Defaults to './log'; set to an absolute writable path for read-only root filesystems.",
+      String.class, "./log"),
+
   SERVER_DATABASE_DIRECTORY("arcadedb.server.databaseDirectory", SCOPE.JVM, "Directory containing the database", String.class,
       "${arcadedb.server.rootPath}/databases"),
 
@@ -655,10 +660,13 @@ Each idle thread reserves a stack (~512KB-1MB) and Thread metadata in heap, so l
 
   HA_SERVER_LIST("arcadedb.ha.serverList", SCOPE.SERVER,
       """
-      Servers in the cluster as a list of <hostname/ip-address:raftPort:httpPort[:priority]> items separated by comma. \
+      Servers in the cluster, comma-separated. Each entry can use either the positional form \
+      <hostname/ip-address:raftPort:httpPort[:priority[:httpsPort]]> or the more readable object form \
+      <hostname/ip-address:{raft:2434,http:2480,https:2490,priority:10}> (fields unordered, all optional except raft defaults to the configured Raft port). Both forms may be mixed and prefixed with an optional 'name@'. \
       The httpPort is required for replica-to-leader HTTP command forwarding. \
       The optional priority (integer, default 0) sets the preferred leader: the node with the highest priority is preferred during elections. \
-      Example: localhost:2434:2480:10,192.168.0.1:2434:2480:0""",
+      The optional httpsPort is used for encrypted peer-to-peer transfers (e.g. snapshot download) when 'arcadedb.ssl.enabled' is true; when omitted on a homogeneous cluster it is derived from this node's local HTTPS listening port. \
+      Examples: localhost:2434:2480:10:2490,192.168.0.1:2434:2480:0:2490 or localhost:{raft:2434,http:2480,https:2490,priority:10},192.168.0.1:{raft:2434,http:2480,https:2490}""",
       String.class, ""),
 
   HA_SERVER_ROLE("arcadedb.ha.serverRole", SCOPE.SERVER,
@@ -793,7 +801,7 @@ Set to an absolute path (e.g. /var/lib/arcadedb/raft) to decouple Raft persisten
       Path to a file containing the shared secret for inter-node request forwarding authentication. \
       Used to keep the secret off the command line (e.g. a Kubernetes Secret mounted on tmpfs). \
       Read only when arcadedb.ha.clusterToken is not set; the file content is trimmed of surrounding whitespace.""",
-      String.class, null),
+      String.class, ""),
 
   HA_HEALTH_CHECK_INTERVAL("arcadedb.ha.healthCheckInterval", SCOPE.SERVER,
       "Interval in milliseconds for the Raft health monitor to check for CLOSED/EXCEPTION state and auto-recover. 0 disables.",
@@ -902,6 +910,22 @@ producing an entry too large for the Raft transport. Kept below the Raft message
       "Maximum acceptable gap between the snapshot index and persisted applied index before triggering a snapshot download.",
       Long.class, 10L),
 
+  HA_STALE_FOLLOWER_LAG_THRESHOLD("arcadedb.ha.staleFollowerLagThreshold", SCOPE.SERVER,
+      """
+      Number of Raft log entries a follower may lag behind the commit index, while NOT actively catching up, before the \
+      health monitor re-arms a snapshot download from the leader. Guards against a follower that diverged (apply failure) \
+      and whose snapshot download also failed on a quiet cluster, where no new entry arrives to re-trigger recovery. \
+      0 (the default) disables stale-follower recovery; the node restart path remains the primary mitigation. \
+      Enable with a value well below HA_SNAPSHOT_THRESHOLD once you have observed normal catch-up lag for your workload, \
+      to avoid multiple followers downloading snapshots from the leader at once.""",
+      Long.class, 0L),
+
+  HA_STALE_FOLLOWER_RECOVERY_DURATION_MS("arcadedb.ha.staleFollowerRecoveryDurationMs", SCOPE.SERVER,
+      """
+      How long in milliseconds the lag described by HA_STALE_FOLLOWER_LAG_THRESHOLD must persist continuously \
+      (across consecutive health-monitor ticks) before recovery is triggered. Avoids acting on transient catch-up lag.""",
+      Long.class, 60_000L),
+
   HA_SNAPSHOT_MAX_ENTRY_SIZE("arcadedb.ha.snapshotMaxEntrySize", SCOPE.SERVER,
       "Maximum uncompressed size in bytes for a single entry in a snapshot ZIP file. Protects against decompression bombs.",
       Long.class, 10_737_418_240L),
@@ -925,6 +949,25 @@ producing an entry too large for the Raft transport. Kept below the Raft message
       "Rate-limiting interval in milliseconds for DNS re-resolution in the gRPC peer address allowlist filter.",
       Long.class, 30_000L),
 
+  HA_PEER_ALLOWLIST_STARTUP_GRACE_MS("arcadedb.ha.peerAllowlistStartupGraceMs", SCOPE.SERVER,
+      """
+      Startup grace window in milliseconds during which the gRPC peer allowlist filter fails OPEN (accepts and logs a \
+      warning) for an inbound address it cannot yet match, as long as it has never resolved every host in \
+      arcadedb.ha.serverList at least once. This prevents a self-inflicted partition on Kubernetes, where a peer's \
+      headless-service DNS record is only published once its pod is Ready, so a legitimately-restarting peer connects \
+      before its own name resolves. Measured from filter creation. Once all peer hosts have resolved at least once, or \
+      the window elapses, the filter enforces normally. Set to 0 to disable fail-open (strict from the first connection); \
+      the filter is not an mTLS substitute (see issue #3890), so a bounded fail-open window is the safer default.""",
+      Long.class, 60_000L),
+
+  HA_PEER_ALLOWLIST_STICKY_TTL_MS("arcadedb.ha.peerAllowlistStickyTtlMs", SCOPE.SERVER,
+      """
+      How long in milliseconds the gRPC peer allowlist filter keeps the last successfully-resolved IPs of a peer host \
+      when a later DNS re-resolution of that host fails. Bridges transient DNS outages and pod-IP churn so a peer that \
+      resolved moments ago is not evicted from the allowlist by a momentary lookup failure. Set to 0 to disable \
+      stickiness (drop a host from the allowlist as soon as it stops resolving).""",
+      Long.class, 300_000L),
+
   // POSTGRES
   POSTGRES_PORT("arcadedb.postgres.port", SCOPE.SERVER,
       "TCP/IP port number used for incoming connections for Postgres plugin. Default is 5432", Integer.class, 5432),