Changes to support resolving gRPC proxies via the Coherence name service.

Author: rlubke

.github/workflows/node.js.yml .github/workflows/build.yml

@@ -1,12 +1,12 @@
-# Copyright 2020, 2023, Oracle Corporation and/or its affiliates.  All rights reserved.
+# Copyright 2020, 2025, Oracle Corporation and/or its affiliates.  All rights reserved.
 # Licensed under the Universal Permissive License v 1.0 as shown at
 # https://oss.oracle.com/licenses/upl.
 
 # ---------------------------------------------------------------------------
 # Coherence JavaScript Client GitHub Actions CI build.
 # ---------------------------------------------------------------------------
 
-name: Node.js CI
+name: JS Client Validation
 
 on:
   schedule:
@@ -18,7 +18,7 @@ on:
     types:
       - opened
     branches:
-    - 'main'
+    - '*'
 jobs:
   build:
 
@@ -28,7 +28,7 @@ jobs:
       fail-fast: false
       matrix:
         node-version: [18.x, 19.x, 20.x, 21.x, 22.x, 23.x]
-        coherence-version: [22.06.11, 24.09.2]
+        coherence-version: [22.06.11, 14.1.2-0-1, 24.09.2]
 
     steps:
     - uses: actions/checkout@v4
@@ -48,7 +48,7 @@ jobs:
     - run: COHERENCE_VERSION=${{ matrix.coherence-version }} npm run test-cycle-tls
     # clean up
     - name: Archive production artifacts
-      if: always()
+      if: failure()
       uses: actions/upload-artifact@v4
       with:
           name: save-log-file-${{ matrix.node-version }}-${{ matrix.coherence-version }}

.github/workflows/discovery.yml

@@ -0,0 +1,68 @@
+# Copyright 2025, Oracle Corporation and/or its affiliates.  All rights reserved.
+# Licensed under the Universal Permissive License v 1.0 as shown at
+# https://oss.oracle.com/licenses/upl.
+
+# ---------------------------------------------------------------------------
+# Coherence JavaScript Client GitHub Actions CI build.
+# ---------------------------------------------------------------------------
+
+name: JS Client Discovery Validation
+
+on:
+  schedule:
+    - cron: "0 5 * * *"
+  push:
+    branches-ignore:
+    - ghpages
+  pull_request:
+    types:
+      - opened
+    branches:
+    - '*'
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: [20.x, 21.x, 22.x, 23.x]
+        coherence-version: [22.06.11, 14.1.2-0-1, 24.09.2]
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ matrix.node-version }}
+    - run: curl -LO "https://github.com/protocolbuffers/protobuf/releases/download/v22.2/protoc-22.2-linux-x86_64.zip"
+    - run: unzip protoc-22.2-linux-x86_64.zip -d /tmp/grpc
+    - run: echo "/tmp/grpc/bin" >> $GITHUB_PATH
+    - run: npm install
+    - run: npm run compile
+
+    - name: Run Coherence Server
+      shell: bash
+      run: |
+        export COHERENCE_VERSION=${{ matrix.coherence-version }}
+        curl -sL https://raw.githubusercontent.com/oracle/coherence-cli/main/scripts/install.sh | bash
+        cohctl version
+        cohctl set profile grpc-cluster1 -v "-Dcoherence.grpc.server.port=10000" -y
+        cohctl create cluster grpc-cluster1 -P grpc-cluster1 -r 1 -v ${{ matrix.coherence-version }} -y -a coherence-grpc-proxy
+        cohctl set profile grpc-cluster2 -v "-Dcoherence.grpc.server.port=10001" -y
+        cohctl create cluster grpc-cluster2 -P grpc-cluster2 -r 1 -H 30001 -v ${{ matrix.coherence-version }} -y -a coherence-grpc-proxy
+        sleep 20
+        cohctl monitor health -n localhost:7574 -T 40 -w
+
+    - name: Run resolver tests
+      shell: bash
+      run: |
+        npm run test-resolver
+
+    - name: Archive production artifacts
+      if: failure()
+      uses: actions/upload-artifact@v4
+      with:
+        name: save-log-file-${{ matrix.node-version }}-${{ matrix.coherence-version }}
+        path: ~/.cohctl/logs/*.*.log

README.md

@@ -12,7 +12,7 @@ the network transport.
 * Registration of listeners to be notified of map mutations
 
 ### Requirements
-* Coherence CE `22.06` or later (or equivalent non-open source editions) with a configured [gRPC Proxy](https://docs.oracle.com/en/middleware/standalone/coherence/14.1.1.2206/develop-remote-clients/using-coherence-grpc-server.html)
+* Coherence CE versions `22.06`, `14.1.2-0-0`, `24.09` or later (or equivalent non-open source editions) with a configured [gRPC Proxy](https://docs.oracle.com/en/middleware/standalone/coherence/14.1.1.2206/develop-remote-clients/using-coherence-grpc-server.html)
 * Node `18.15.x` or later
 * NPM `9.x` or later
 
@@ -40,7 +40,7 @@ For more details on the image, see the [documentation](https://github.com/oracle
 
 ### Declare Your Dependency
 
-To use the Coherence gRPC JavaScript Client, simply declare it as a dependency in your
+To use the JavaScript Client for Oracle Coherence, simply declare it as a dependency in your
 project's `package.json`:
 ```
 ...
@@ -52,8 +52,8 @@ project's `package.json`:
 
 ### Compatibility with Java Types
 The following table provides a listing of mappings between Java types and Javascript types when working with
-Coherence `23.09` or later.  If using Coherence `22.06.x`, these types will be returned as Number.  It is recommended
-using `23.09` if intentionally using `java.math.BigInteger` or `java.math.BigDecimal` as part of your application.
+Coherence `24.09` or later.  If using Coherence `22.06.x`, these types will be returned as Number.  It is recommended
+using `24.09` if intentionally using `java.math.BigInteger` or `java.math.BigDecimal` as part of your application.
 
 | Java Type            | JavascriptType         |
 |----------------------|------------------------|
@@ -68,15 +68,15 @@ using `23.09` if intentionally using `java.math.BigInteger` or `java.math.BigDec
 #### Establishing a Session
 
 The Coherence uses the concept of a `Session` to manage a set of related Coherence resources,
-such as maps and/or caches. When using the Coherence JavaScript Client, a `Session` connects to a specific
+such as maps and/or caches. When using the JavaScript Client for Oracle Coherence, a `Session` connects to a specific
 gRPC endpoint and uses a specific serialization format to marshal requests and responses.
 This means that different sessions using different serializers may connect to the same server endpoint. Typically,
 for efficiency the client and server would be configured to use matching serialization formats to avoid
 deserialization of data on the server, but this does not have to be the case. If the server is using a different
 serializer for the server-side caches, it must be able to deserialize the client's requests, so there must be
 a serializer configured on the server to match that used by the client.
 
-> NOTE: Currently, the Coherence JavaScript client only supports JSON serialization
+> NOTE: Currently, the JavaScript Client for Oracle Coherence only supports JSON serialization
 
 A `Session` is constructed using an `Options` instance, or a generic object with the same keys and values.
 
@@ -126,6 +126,32 @@ const opts = new Options({address: 'example.com:4444'})
 let session = new Session(opts)
 ```
 
+As of v1.2.3 of the JavaScript Client for Oracle Coherence, it's now possible to use the Coherence
+NameService to lookup gRPC Proxy endpoints.  The format to enable this feature is
+`coherence:///<host>([:port]|[:cluster-name]|[:port:cluster-name])`
+
+For example:
+ * `coherence:///localhost` will connect to the name service bound to a local coherence cluster on port `7574` (the default Coherence cluster port).
+ * `coherence:///localhost:8000` will connect to the name service bound to a local coherence cluster on port `8000`.
+ * `coherence:///localhost:remote-cluster` will connect to the name service bound to a local coherence cluster on port `7574` (the default Coherence cluster port) and look up the name service for the given cluster name.  Note: this typically means both clusters have a local member sharing a cluster port.
+ * `coherence:///localhost:8000:remote-cluster` will connect to the name service bound to a local coherence cluster on port `8000` and look up the name service for the given cluster name.  Note: this typically means both clusters have a local member sharing a cluster port.
+
+While this is useful for local development, this may have limited uses in a production environment.  For example,
+Coherence running within a container with the cluster port (`7574`) exposed so external clients may connect.  The
+lookup will fail to work for the client as the Coherence name service return a private network address which
+won't resolve. Lastly, if connecting to a cluster that has multiple proxies bound to different ports, gRPC, by default,
+will use the first address returned by the resolver.  It is possible to enable round-robin load balancing by including
+a custom channel option when creating the session:
+
+```typescript
+const { Session } = require('@oracle/coherence')
+
+const opts = new Options({address: 'example.com:4444',
+  channelOptions: {'grpc.service_config': JSON.stringify({ loadBalancingConfig: [{ round_robin: {} }], })}})
+
+let session = new Session(opts)
+```
+
 It's also possible to control the default address the session will bind to by providing
 an address via the `COHERENCE_SERVER_ADDRESS` environment variable.  The format of the value would
 be the same as if you configured it programmatically as the above example shows.

etc/docker-compose-2-members.yaml

@@ -19,6 +19,7 @@ services:
       - "9612:9612"
       - "8080:8080"
       - "6676:6676"
+      - "7574:7574"
     volumes:
       - .:/args
       - ./cert:/certs

etc/jvm-args-clear.txt

@@ -1,9 +1,9 @@
-# Copyright (c) 2023, Oracle and/or its affiliates.
+# Copyright (c) 2023, 2025, Oracle and/or its affiliates.
 #
 # Licensed under the Universal Permissive License v 1.0 as shown at
 # https://oss.oracle.com/licenses/upl.
 
 -Xms1g
 -Xmx1g
 -Dcoherence.log.level=9
--Dcoherence.io.json.debug=true
+-Dcoherence.io.json.debug=false

etc/jvm-args-tls.txt

@@ -1,12 +1,12 @@
-# Copyright (c) 2023, Oracle and/or its affiliates.
+# Copyright (c) 2023, 2025, Oracle and/or its affiliates.
 #
 # Licensed under the Universal Permissive License v 1.0 as shown at
 # https://oss.oracle.com/licenses/upl.
 
 -Xms1g
 -Xmx1g
 -Dcoherence.log.level=9
--Dcoherence.io.json.debug=true
+-Dcoherence.io.json.debug=false
 -Dcoherence.grpc.server.socketprovider=tls-files
 -Dcoherence.security.key=/certs/star-lord.pem
 -Dcoherence.security.cert=/certs/star-lord.crt