nacos-sdk-rust-binding-node 0.5.3 → 0.7.0

package/AGENTS.md

@@ -0,0 +1,148 @@
+# AGENTS.md
+
+This file provides guidance to AI coding agents when working with code in this repository.
+
+## Project Overview
+
+This is a Node.js native addon providing bindings to the Nacos service discovery and configuration management system. It uses [napi-rs](https://napi.rs/) to bridge Rust (`nacos-sdk-rust`) with Node.js/TypeScript, offering better performance than the official JavaScript SDK which lacks gRPC support.
+
+## Architecture
+
+### Hybrid Rust/Node.js Structure
+
+- **Rust Layer** (`src/*.rs`): Core Nacos client implementation using `nacos-sdk-rust`
+  - `lib.rs`: Entry point, `ClientOptions` struct
+  - `config.rs`: Configuration management (`NacosConfigClient`)
+  - `naming.rs`: Service discovery (`NacosNamingClient`)
+  - `plugin.rs`: Config filter plugin interface for encryption/decryption
+
+- **TypeScript Definitions** (`index.d.ts`): Auto-generated from Rust code via `napi-rs` during build
+
+### Key Data Flows
+
+1. **Config Client**: `getConfig()` → Rust SDK → Nacos Server → async response
+2. **Naming Client**: `registerInstance()` → Rust SDK → Nacos Server → async response
+3. **Subscriptions**: Rust SDK maintains long-lived gRPC connections; pushes updates via `ThreadsafeFunction` callbacks to JS
+
+### Type Conventions
+
+- Rust `Option<T>` maps to TypeScript `T | undefined | null`
+- Async Rust methods return JavaScript Promises
+- Callbacks use `ThreadsafeFunction` for thread-safe JS invocation from Rust
+- Nacos errors are converted to JS `Error` with reason string
+
+## Build System
+
+This project uses:
+- **Cargo**: Rust dependency management and compilation
+- **napi-rs**: Native Node.js addon framework
+- **Yarn 3.4.1**: Package manager (specified in `packageManager` field)
+
+### Common Commands
+
+```bash
+# Install dependencies
+yarn install
+
+# Build debug native addon (faster, for development)
+yarn build:debug
+
+# Build release native addon (optimized)
+yarn build
+
+# Run tests (requires compiled .node file)
+yarn test
+
+# Collect build artifacts for distribution
+yarn artifacts
+
+# Create universal macOS binary (combines x64 + arm64)
+yarn universal
+```
+
+### Cross-Compilation Targets
+
+The CI builds for multiple platforms (see `.github/workflows/CI.yml`):
+- macOS: `x86_64-apple-darwin`, `aarch64-apple-darwin`, `universal-apple-darwin`
+- Linux: `x86_64-unknown-linux-gnu/musl`, `aarch64-unknown-linux-gnu/musl`, `armv7-unknown-linux-gnueabihf`
+- Windows: `x86_64-pc-windows-msvc`, `i686-pc-windows-msvc`, `aarch64-pc-windows-msvc`
+- Android: `aarch64-linux-android`, `armv7-linux-androideabi`
+
+Target-specific builds: `yarn build --target <target-triple>`
+
+### Build Outputs
+
+- Compiled native addon: `nacos-sdk-rust-binding-node.<platform>.node`
+- TypeScript definitions: `index.d.ts` (auto-generated)
+
+## Testing
+
+Uses [AVA](https://github.com/avajs/ava) test framework with 3-minute timeout:
+
+```bash
+# Run all tests
+yarn test
+
+# Run a specific test file
+yarn test __test__/index.spec.mjs
+```
+
+Note: Tests require the native addon to be built first (`index.node` must exist).
+
+## Environment Variables
+
+- `NACOS_CLIENT_LOGGER_LEVEL`: Log level (default: `INFO`, logs to `$HOME/logs/nacos/`)
+- `NACOS_CLIENT_COMMON_THREAD_CORES`: Client thread pool size (default: `1`)
+- `NACOS_CLIENT_NAMING_PUSH_EMPTY_PROTECTION`: Protect against empty service list pushes (default: `true`)
+
+See [nacos-sdk-rust docs](https://github.com/nacos-group/nacos-sdk-rust) for more environment variables.
+
+## API Usage Patterns
+
+### Config Client
+
+```javascript
+const { NacosConfigClient } = require('nacos-sdk-rust-binding-node');
+
+const client = new NacosConfigClient({
+  serverAddr: '127.0.0.1:8848',
+  namespace: 'my-namespace',
+  // Optional auth:
+  username: 'user',
+  password: 'pass'
+});
+
+const content = await client.getConfig('dataId', 'group');
+await client.addListener('dataId', 'group', (err, config) => {
+  // Handle push updates
+});
+```
+
+### Naming Client
+
+```javascript
+const { NacosNamingClient } = require('nacos-sdk-rust-binding-node');
+
+const client = new NacosNamingClient({
+  serverAddr: '127.0.0.1:8848',
+  namespace: 'my-namespace'
+});
+
+await client.registerInstance('service', 'group', {
+  ip: '192.168.1.1',
+  port: 8080
+});
+```
+
+## Important Implementation Notes
+
+- **removeListener/unSubscribe**: These are NOOPs - the underlying Rust SDK doesn't implement removal, but this is typically not problematic as listeners are long-lived
+- **Clients are stateful**: Each client maintains persistent gRPC connections; create once and reuse for the application lifecycle
+- **Auth methods**: Supports HTTP token auth (username/password) or Alibaba Cloud RAM (access_key/access_secret)
+- **Build dependency**: require `nacos-sdk-rust` and `napi`
+
+## Troubleshooting
+
+- If build fails, ensure Rust toolchain is up to date: `rustup update stable && cargo update`
+- For cross-compilation issues, refer to the Docker images and setup in CI workflow
+- Native addon loading errors usually indicate platform/architecture mismatch between build target and runtime

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "nacos-sdk-rust-binding-node"
-version = "0.5.3"
+version = "0.7.0"
 edition = "2024"
 license = "Apache-2.0"
 publish = false
@@ -19,10 +19,11 @@ crate-type = ["cdylib"]
 napi = { version = "2", default-features = false, features = ["napi4", "async"] }
 napi-derive = "2"
 
-#nacos-sdk = { version = "0.5.3", features = ["default", "auth-by-aliyun", "tracing-log"] }
-nacos-sdk = { git = "https://github.com/nacos-group/nacos-sdk-rust.git", branch = "main", features = ["default", "auth-by-aliyun", "tracing-log"] }
+nacos-sdk = { version = "0.7.0", features = ["default", "auth-by-aliyun", "tracing-log"] }
+#nacos-sdk = { git = "https://github.com/nacos-group/nacos-sdk-rust.git", branch = "main", features = ["default", "auth-by-aliyun", "tracing-log"] }
 
 async-trait = "0.1"
+tokio = { version = "1", features = ["rt"] }
 
 [build-dependencies]
 napi-build = "2"

package/README.md

@@ -13,7 +13,7 @@ npm 包 -> https://www.npmjs.com/package/nacos-sdk-rust-binding-node
 
 环境变量 `NACOS_CLIENT_COMMON_THREAD_CORES=4` 可设置客户端核心线程数，默认 1
 
-环境变量 `ENV_NACOS_CLIENT_NAMING_PUSH_EMPTY_PROTECTION=false` 可关闭 Naming 防推空保护，默认 true
+环境变量 `NACOS_CLIENT_NAMING_PUSH_EMPTY_PROTECTION=false` 可关闭 Naming 防推空保护，默认 true
 
 更多环境变量请看 `nacos-sdk-rust` 的[文档说明](https://github.com/nacos-group/nacos-sdk-rust)
 

package/example/config.js

@@ -11,17 +11,29 @@ const nacos_config_client = new NacosConfigClient({
     appName: "binding-node-example-app"
 });
 
-try {
-    // If it fails, pay attention to err
-    nacos_config_client.getConfig('todo-dataid', 'LOVE').then(data => {
+// getConfig - config may not exist, handle error gracefully
+nacos_config_client.getConfig('todo-dataid', 'LOVE')
+    .then(data => {
         console.log('getConfig => ' + data);
+    })
+    .catch(err => {
+        console.log('getConfig error: ' + err.message);
     });
 
-    nacos_config_client.getConfigResp('todo-dataid', 'LOVE').then(data => {
+// getConfigResp - config may not exist, handle error gracefully
+nacos_config_client.getConfigResp('todo-dataid', 'LOVE')
+    .then(data => {
         console.log('getConfigResp => ' + JSON.stringify(data));
+    })
+    .catch(err => {
+        console.log('getConfigResp error: ' + err.message);
     });
-} catch(e) {
-    console.log(e);
-}
 
-nacos_config_client.addListener('todo-dataid', 'LOVE', (err, config_resp) => { console.log(config_resp) });
+// addListener - listener will be called when config is created/changed
+nacos_config_client.addListener('todo-dataid', 'LOVE', (err, config_resp) => {
+    if (err) {
+        console.log('addListener error: ' + err.message);
+    } else {
+        console.log('config changed => ' + JSON.stringify(config_resp));
+    }
+});

package/example/config_decrypt.js

@@ -27,17 +27,29 @@ const nacos_config_client = new NacosConfigClient(
 }
 );
 
-try {
-    // If it fails, pay attention to err
-    nacos_config_client.getConfig('todo-dataid', 'LOVE').then(data => {
+// getConfig - config may not exist, handle error gracefully
+nacos_config_client.getConfig('todo-dataid', 'LOVE')
+    .then(data => {
         console.log('getConfig => ' + data);
+    })
+    .catch(err => {
+        console.log('getConfig error (config may not exist): ' + err.message);
     });
-   
-    nacos_config_client.getConfigResp('todo-dataid', 'LOVE').then((data) => {
+
+// getConfigResp - config may not exist, handle error gracefully
+nacos_config_client.getConfigResp('todo-dataid', 'LOVE')
+    .then(data => {
         console.log('getConfigResp => ' + JSON.stringify(data));
+    })
+    .catch(err => {
+        console.log('getConfigResp error (config may not exist): ' + err.message);
     });
-} catch(e) {
-    console.log(e);
-}
 
-nacos_config_client.addListener('todo-dataid', 'LOVE', (err, config_resp) => { console.log(config_resp) });
+// addListener - listener will be called when config is created/changed
+nacos_config_client.addListener('todo-dataid', 'LOVE', (err, config_resp) => {
+    if (err) {
+        console.log('addListener error: ' + err.message);
+    } else {
+        console.log('config changed => ' + JSON.stringify(config_resp));
+    }
+});

package/index.d.ts

@@ -1,9 +1,99 @@
-/* auto-generated by NAPI-RS */
+/* tslint:disable */
 /* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+export declare function sum(a: number, b: number): number
+export interface ClientOptions {
+  /** Server Addr, e.g. address:port[,address:port],...] */
+  serverAddr: string
+  /** Namespace/Tenant */
+  namespace: string
+  /** AppName */
+  appName?: string
+  /** Username for Auth, Login by Http with Token */
+  username?: string
+  /** Password for Auth, Login by Http with Token */
+  password?: string
+  /** Access_Key for Auth, Login by Aliyun Ram */
+  accessKey?: string
+  /** Access_Secret for Auth, Login by Aliyun Ram */
+  accessSecret?: string
+  /** Signature_Region_Id for Auth, Login by Aliyun Ram */
+  signatureRegionId?: string
+  /** naming push_empty_protection, default true */
+  namingPushEmptyProtection?: boolean
+  /** naming load_cache_at_start, default false */
+  namingLoadCacheAtStart?: boolean
+  /** config load_cache_at_start, default false */
+  configLoadCacheAtStart?: boolean
+}
+export interface NacosConfigResponse {
+  /** Namespace/Tenant */
+  namespace: string
+  /** DataId */
+  dataId: string
+  /** Group */
+  group: string
+  /** Content */
+  content: string
+  /** Content's Type; e.g. json,properties,xml,html,text,yaml */
+  contentType: string
+  /** Content's md5 */
+  md5: string
+}
+export interface NacosServiceInstance {
+  /** Instance Id */
+  instanceId?: string
+  /** Ip */
+  ip: string
+  /** Port */
+  port: number
+  /** Weight, default 1.0 */
+  weight?: number
+  /** Healthy or not, default true */
+  healthy?: boolean
+  /** Enabled ot not, default true */
+  enabled?: boolean
+  /** Ephemeral or not, default true */
+  ephemeral?: boolean
+  /** Cluster Name, default 'DEFAULT' */
+  clusterName?: string
+  /** Service Name */
+  serviceName?: string
+  /** Metadata, default '{}' */
+  metadata?: Record<string, string>
+}
+/** ConfigReq for [`ConfigFilter`] */
+export interface NacosConfigReq {
+  /** DataId */
+  dataId: string
+  /** Group */
+  group: string
+  /** Namespace/Tenant */
+  namespace: string
+  /** Content */
+  content: string
+  /** Content's Encrypted Data Key. */
+  encryptedDataKey: string
+}
+/** ConfigResp for [`ConfigFilter`] */
+export interface NacosConfigResp {
+  /** DataId */
+  dataId: string
+  /** Group */
+  group: string
+  /** Namespace/Tenant */
+  namespace: string
+  /** Content */
+  content: string
+  /** Content's Encrypted Data Key. */
+  encryptedDataKey: string
+}
 /** Client api of Nacos Config. */
-export declare class NacosConfigClient {
+export class NacosConfigClient {
   /** Build a Config Client. */
-  constructor(clientOptions: ClientOptions, configFilter?: (((err: Error | null, arg0?: NacosConfigReq | undefined | null, arg1?: NacosConfigResp | undefined | null) => any)) | undefined | null)
+  constructor(clientOptions: ClientOptions, configFilter?: (err: Error | null, arg0?: NacosConfigReq | undefined | null, arg1?: NacosConfigResp | undefined | null) => any | undefined | null)
   /**
    * Get config's content.
    * If it fails, pay attention to err
@@ -28,17 +118,16 @@ export declare class NacosConfigClient {
    * Add NacosConfigChangeListener callback func, which listen the config change.
    * If it fails, pay attention to err
    */
-  addListener(dataId: string, group: string, listener: ((err: Error | null, arg: NacosConfigResponse) => any)): Promise<void>
+  addListener(dataId: string, group: string, listener: (err: Error | null, arg: NacosConfigResponse) => any): Promise<void>
   /**
    * Remove NacosConfigChangeListener callback func, but noop....
    * The logic is not implemented internally, and only APIs are provided as compatibility.
    * Users maybe do not need it? Not removing the listener is not a big problem, Sorry!
    */
-  removeListener(dataId: string, group: string, listener: ((err: Error | null, arg: NacosConfigResponse) => any)): Promise<void>
+  removeListener(dataId: string, group: string, listener: (err: Error | null, arg: NacosConfigResponse) => any): Promise<void>
 }
-
 /** Client api of Nacos Naming. */
-export declare class NacosNamingClient {
+export class NacosNamingClient {
   /** Build a Naming Client. */
   constructor(clientOptions: ClientOptions)
   /**
@@ -75,102 +164,11 @@ export declare class NacosNamingClient {
    * Add NacosNamingEventListener callback func, which listen the instance change.
    * If it fails, pay attention to err
    */
-  subscribe(serviceName: string, group: string, clusters: Array<string> | undefined | null, listener: ((err: Error | null, arg: Array<NacosServiceInstance>) => any)): Promise<void>
+  subscribe(serviceName: string, group: string, clusters: Array<string> | undefined | null, listener: (err: Error | null, arg: Array<NacosServiceInstance>) => any): Promise<void>
   /**
    * Remove NacosNamingEventListener callback func, but noop....
    * The logic is not implemented internally, and only APIs are provided as compatibility.
    * Users maybe do not need it? Not removing the subscription is not a big problem, Sorry!
    */
-  unSubscribe(serviceName: string, group: string, clusters: Array<string> | undefined | null, listener: ((err: Error | null, arg: Array<NacosServiceInstance>) => any)): Promise<void>
+  unSubscribe(serviceName: string, group: string, clusters: Array<string> | undefined | null, listener: (err: Error | null, arg: Array<NacosServiceInstance>) => any): Promise<void>
 }
-
-export interface ClientOptions {
-  /** Server Addr, e.g. address:port[,address:port],...] */
-  serverAddr: string
-  /** Namespace/Tenant */
-  namespace: string
-  /** AppName */
-  appName?: string
-  /** Username for Auth, Login by Http with Token */
-  username?: string
-  /** Password for Auth, Login by Http with Token */
-  password?: string
-  /** Access_Key for Auth, Login by Aliyun Ram */
-  accessKey?: string
-  /** Access_Secret for Auth, Login by Aliyun Ram */
-  accessSecret?: string
-  /** Signature_Region_Id for Auth, Login by Aliyun Ram */
-  signatureRegionId?: string
-  /** naming push_empty_protection, default true */
-  namingPushEmptyProtection?: boolean
-  /** naming load_cache_at_start, default false */
-  namingLoadCacheAtStart?: boolean
-}
-
-/** ConfigReq for [`ConfigFilter`] */
-export interface NacosConfigReq {
-  /** DataId */
-  dataId: string
-  /** Group */
-  group: string
-  /** Namespace/Tenant */
-  namespace: string
-  /** Content */
-  content: string
-  /** Content's Encrypted Data Key. */
-  encryptedDataKey: string
-}
-
-/** ConfigResp for [`ConfigFilter`] */
-export interface NacosConfigResp {
-  /** DataId */
-  dataId: string
-  /** Group */
-  group: string
-  /** Namespace/Tenant */
-  namespace: string
-  /** Content */
-  content: string
-  /** Content's Encrypted Data Key. */
-  encryptedDataKey: string
-}
-
-export interface NacosConfigResponse {
-  /** Namespace/Tenant */
-  namespace: string
-  /** DataId */
-  dataId: string
-  /** Group */
-  group: string
-  /** Content */
-  content: string
-  /** Content's Type; e.g. json,properties,xml,html,text,yaml */
-  contentType: string
-  /** Content's md5 */
-  md5: string
-}
-
-export interface NacosServiceInstance {
-  /** Instance Id */
-  instanceId?: string
-  /** Ip */
-  ip: string
-  /** Port */
-  port: number
-  /** Weight, default 1.0 */
-  weight?: number
-  /** Healthy or not, default true */
-  healthy?: boolean
-  /** Enabled ot not, default true */
-  enabled?: boolean
-  /** Ephemeral or not, default true */
-  ephemeral?: boolean
-  /** Cluster Name, default 'DEFAULT' */
-  clusterName?: string
-  /** Service Name */
-  serviceName?: string
-  /** Metadata, default '{}' */
-  metadata?: Record<string, string>
-}
-
-export declare function sum(a: number, b: number): number