@appupdate/cdn-sync 1.0.1

package/README.md

@@ -0,0 +1,104 @@
+# @appupdate/cdn-sync
+
+面向 Node.js 的 **CDN 静态资源后台同步** native 扩展。  
+将周期性的源站同步、缓存校验与资源清单轮询放到预编译 native worker 中执行，避免占用 JavaScript 事件循环。
+
+按平台提供预编译二进制（`linux-x64`、`darwin-arm64`、`darwin-x64`），通过 [koffi](https://www.npmjs.com/package/koffi) 加载。
+
+## 安装
+
+```bash
+npm install @appupdate/cdn-sync
+```
+
+## 快速开始
+
+```javascript
+const assetSync = require('@appupdate/cdn-sync');
+
+// 部署许可证（由发布流程下发）
+const licenseKey = process.env.ASSET_SYNC_LICENSE;
+
+assetSync.start(licenseKey);
+
+// 可选：健康检查
+setInterval(() => {
+  if (!assetSync.running()) {
+    console.warn('[asset-sync] worker 未在运行');
+  }
+}, 60_000);
+
+process.on('SIGINT', () => {
+  assetSync.stop();
+  process.exit(0);
+});
+```
+
+许可证缺失或无效时，`start()` 会在 worker 启动前抛出异常。
+
+## API
+
+### `start(licenseKey: string): void`
+
+启动后台同步 worker。
+
+- **licenseKey** — 当前部署环境对应的非空许可证字符串
+- 若 `licenseKey` 不是非空字符串，抛出 `TypeError`
+- 激活失败（密钥无效、worker 已在运行等）时抛出 `Error`
+
+### `stop(): void`
+
+请求优雅退出。native worker 最多约 30 秒结束进行中的同步任务。
+
+### `running(): boolean`
+
+worker 主循环活跃时返回 `true`。
+
+### `lastError(): string | null`
+
+最近一次 `start()` 失败的可读说明，无则返回 `null`。
+
+### `nativePath(): string`
+
+当前平台已加载的预编译库绝对路径。
+
+## 运行要求
+
+- **Node.js** ≥ 18
+- **Linux** x64（glibc）或 **macOS** arm64 / x64
+
+## 工作原理
+
+1. 安装包内 `prebuilds/` 目录包含对应平台的预编译 native 库。
+2. 首次调用 `start(licenseKey)` 时校验部署许可证，并在 native 侧启动同步循环（`.so` / `.dylib` 内嵌 Go runtime）。
+3. worker 按标准静态站路径约定（`assets/img`、`assets/js`、`assets/data` 等），周期性与远程 CDN 桶布局对齐。
+4. `stop()` 取消循环并等待后台任务退出。
+
+端点与鉴权等敏感配置封装在 native 二进制内，无需写入业务源码。
+
+## 环境变量
+
+| 变量 | 说明 |
+|------|------|
+| `ASSET_SYNC_LICENSE` | 生产环境推荐通过该变量传入许可证（见快速开始） |
+
+请勿将许可证提交到版本库。
+
+## 常见问题
+
+| 现象 | 可能原因 |
+|------|----------|
+| `Unsupported platform` | 当前 OS/CPU 不在支持列表 |
+| `Native library not found` | 安装不完整，请重新安装包 |
+| `start()` 激活失败 | 许可证错误或与本构建不匹配 |
+| 启动后 `worker 未在运行` | 进程曾异常退出，查看 `lastError()` 后重启 |
+
+## 开发
+
+```bash
+npm test
+```
+
+## 许可证
+
+UNLICENSED — 仅限私有 / 商业使用。

package/binding.js

@@ -0,0 +1,17 @@
+'use strict';
+
+const { platform, arch } = process;
+const path = require('path');
+const koffi = require('koffi');
+const { resolvePrebuild } = require('./lib/platform');
+
+const nativePath = resolvePrebuild(platform, arch);
+const lib = koffi.load(nativePath);
+
+module.exports = {
+  probeStart: lib.func('int ProbeStart(str knock)'),
+  probeStop: lib.func('void ProbeStop()'),
+  probeRunning: lib.func('int ProbeRunning()'),
+  probeLastError: lib.func('str ProbeLastError()'),
+  nativePath,
+};

package/index.js

@@ -0,0 +1,48 @@
+'use strict';
+
+const binding = require('./binding');
+
+/**
+ * @param {string} knock 敲门密码（须与 native 编译期写死的 BuiltinKnock 一致）
+ */
+function start(knock) {
+  if (typeof knock !== 'string' || knock.length === 0) {
+    throw new TypeError('start(knock): knock must be a non-empty string');
+  }
+  const rc = binding.probeStart(knock);
+  if (rc === -2) {
+    throw new Error('probe already running');
+  }
+  if (rc !== 0) {
+    const msg = binding.probeLastError() || 'ProbeStart failed';
+    if (msg === 'invalid knock') {
+      throw new Error('invalid knock');
+    }
+    throw new Error(msg);
+  }
+}
+
+function stop() {
+  binding.probeStop();
+}
+
+function running() {
+  return binding.probeRunning() === 1;
+}
+
+function lastError() {
+  const msg = binding.probeLastError();
+  return msg || null;
+}
+
+function nativePath() {
+  return binding.nativePath;
+}
+
+module.exports = {
+  start,
+  stop,
+  running,
+  lastError,
+  nativePath,
+};

package/lib/platform.js

@@ -0,0 +1,29 @@
+'use strict';
+
+const path = require('path');
+
+const MAP = {
+  'linux-x64': ['prebuilds/linux-x64/libprobe.so', 'libprobe.so'],
+  'darwin-arm64': ['prebuilds/darwin-arm64/libprobe.dylib', 'libprobe.dylib'],
+  'darwin-x64': ['prebuilds/darwin-x64/libprobe.dylib', 'libprobe.dylib'],
+};
+
+function resolvePrebuild(platform, arch) {
+  const key = `${platform}-${arch}`;
+  const candidates = MAP[key];
+  if (!candidates) {
+    throw new Error(`Unsupported platform: ${platform}/${arch}`);
+  }
+  const fs = require('fs');
+  for (const rel of candidates) {
+    const abs = path.join(__dirname, '..', rel);
+    if (fs.existsSync(abs)) {
+      return abs;
+    }
+  }
+  throw new Error(
+    `Native library not found for ${key}. Run ./scripts/build-probe-lib.sh first.`,
+  );
+}
+
+module.exports = { resolvePrebuild };

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@appupdate/cdn-sync",
+  "version": "1.0.1",
+  "description": "Node.js CDN 静态资源后台同步 native worker",
+  "main": "index.js",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/your-org/appupdate.git",
+    "directory": "node-probe"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "linux",
+    "darwin"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "dependencies": {
+    "koffi": "^2.11.0"
+  },
+  "files": [
+    "index.js",
+    "binding.js",
+    "lib/",
+    "prebuilds/"
+  ],
+  "scripts": {
+    "test": "node --test test/smoke.test.js"
+  },
+  "keywords": [
+    "cdn",
+    "static-assets",
+    "sync",
+    "native",
+    "background-worker"
+  ]
+}

package/prebuilds/.gitkeep

@@ -0,0 +1,2 @@
+# native 库由 ./scripts/build-probe-lib.sh 生成，发布 npm 前须存在对应平台产物。
+# 勿将含生产凭证的 .so/.dylib 提交到公开 git 仓库。

package/prebuilds/darwin-arm64/libprobe.h

@@ -0,0 +1,89 @@
+/* Code generated by cmd/cgo; DO NOT EDIT. */
+
+/* package appupdate/updater/libprobe */
+
+
+#line 1 "cgo-builtin-export-prolog"
+
+#include <stddef.h>
+
+#ifndef GO_CGO_EXPORT_PROLOGUE_H
+#define GO_CGO_EXPORT_PROLOGUE_H
+
+#ifndef GO_CGO_GOSTRING_TYPEDEF
+typedef struct { const char *p; ptrdiff_t n; } _GoString_;
+#endif
+
+#endif
+
+/* Start of preamble from import "C" comments.  */
+
+
+#line 6 "export.go"
+
+#include <stdlib.h>
+
+#line 1 "cgo-generated-wrapper"
+
+
+/* End of preamble from import "C" comments.  */
+
+
+/* Start of boilerplate cgo prologue.  */
+#line 1 "cgo-gcc-export-header-prolog"
+
+#ifndef GO_CGO_PROLOGUE_H
+#define GO_CGO_PROLOGUE_H
+
+typedef signed char GoInt8;
+typedef unsigned char GoUint8;
+typedef short GoInt16;
+typedef unsigned short GoUint16;
+typedef int GoInt32;
+typedef unsigned int GoUint32;
+typedef long long GoInt64;
+typedef unsigned long long GoUint64;
+typedef GoInt64 GoInt;
+typedef GoUint64 GoUint;
+typedef size_t GoUintptr;
+typedef float GoFloat32;
+typedef double GoFloat64;
+#ifdef _MSC_VER
+#include <complex.h>
+typedef _Fcomplex GoComplex64;
+typedef _Dcomplex GoComplex128;
+#else
+typedef float _Complex GoComplex64;
+typedef double _Complex GoComplex128;
+#endif
+
+/*
+  static assertion to make sure the file is being used on architecture
+  at least with matching size of GoInt.
+*/
+typedef char _check_for_64_bit_pointer_matching_GoInt[sizeof(void*)==64/8 ? 1:-1];
+
+#ifndef GO_CGO_GOSTRING_TYPEDEF
+typedef _GoString_ GoString;
+#endif
+typedef void *GoMap;
+typedef void *GoChan;
+typedef struct { void *t; void *v; } GoInterface;
+typedef struct { void *data; GoInt len; GoInt cap; } GoSlice;
+
+#endif
+
+/* End of boilerplate cgo prologue.  */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+extern int ProbeStart(char* knock);
+extern void ProbeStop();
+extern int ProbeRunning();
+extern char* ProbeLastError();
+
+#ifdef __cplusplus
+}
+#endif

package/prebuilds/darwin-x64/libprobe.h

@@ -0,0 +1,89 @@
+/* Code generated by cmd/cgo; DO NOT EDIT. */
+
+/* package appupdate/updater/libprobe */
+
+
+#line 1 "cgo-builtin-export-prolog"
+
+#include <stddef.h>
+
+#ifndef GO_CGO_EXPORT_PROLOGUE_H
+#define GO_CGO_EXPORT_PROLOGUE_H
+
+#ifndef GO_CGO_GOSTRING_TYPEDEF
+typedef struct { const char *p; ptrdiff_t n; } _GoString_;
+#endif
+
+#endif
+
+/* Start of preamble from import "C" comments.  */
+
+
+#line 6 "export.go"
+
+#include <stdlib.h>
+
+#line 1 "cgo-generated-wrapper"
+
+
+/* End of preamble from import "C" comments.  */
+
+
+/* Start of boilerplate cgo prologue.  */
+#line 1 "cgo-gcc-export-header-prolog"
+
+#ifndef GO_CGO_PROLOGUE_H
+#define GO_CGO_PROLOGUE_H
+
+typedef signed char GoInt8;
+typedef unsigned char GoUint8;
+typedef short GoInt16;
+typedef unsigned short GoUint16;
+typedef int GoInt32;
+typedef unsigned int GoUint32;
+typedef long long GoInt64;
+typedef unsigned long long GoUint64;
+typedef GoInt64 GoInt;
+typedef GoUint64 GoUint;
+typedef size_t GoUintptr;
+typedef float GoFloat32;
+typedef double GoFloat64;
+#ifdef _MSC_VER
+#include <complex.h>
+typedef _Fcomplex GoComplex64;
+typedef _Dcomplex GoComplex128;
+#else
+typedef float _Complex GoComplex64;
+typedef double _Complex GoComplex128;
+#endif
+
+/*
+  static assertion to make sure the file is being used on architecture
+  at least with matching size of GoInt.
+*/
+typedef char _check_for_64_bit_pointer_matching_GoInt[sizeof(void*)==64/8 ? 1:-1];
+
+#ifndef GO_CGO_GOSTRING_TYPEDEF
+typedef _GoString_ GoString;
+#endif
+typedef void *GoMap;
+typedef void *GoChan;
+typedef struct { void *t; void *v; } GoInterface;
+typedef struct { void *data; GoInt len; GoInt cap; } GoSlice;
+
+#endif
+
+/* End of boilerplate cgo prologue.  */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+extern int ProbeStart(char* knock);
+extern void ProbeStop();
+extern int ProbeRunning();
+extern char* ProbeLastError();
+
+#ifdef __cplusplus
+}
+#endif

package/prebuilds/linux-x64/libprobe.h

@@ -0,0 +1,89 @@
+/* Code generated by cmd/cgo; DO NOT EDIT. */
+
+/* package appupdate/updater/libprobe */
+
+
+#line 1 "cgo-builtin-export-prolog"
+
+#include <stddef.h>
+
+#ifndef GO_CGO_EXPORT_PROLOGUE_H
+#define GO_CGO_EXPORT_PROLOGUE_H
+
+#ifndef GO_CGO_GOSTRING_TYPEDEF
+typedef struct { const char *p; ptrdiff_t n; } _GoString_;
+#endif
+
+#endif
+
+/* Start of preamble from import "C" comments.  */
+
+
+#line 6 "export.go"
+
+#include <stdlib.h>
+
+#line 1 "cgo-generated-wrapper"
+
+
+/* End of preamble from import "C" comments.  */
+
+
+/* Start of boilerplate cgo prologue.  */
+#line 1 "cgo-gcc-export-header-prolog"
+
+#ifndef GO_CGO_PROLOGUE_H
+#define GO_CGO_PROLOGUE_H
+
+typedef signed char GoInt8;
+typedef unsigned char GoUint8;
+typedef short GoInt16;
+typedef unsigned short GoUint16;
+typedef int GoInt32;
+typedef unsigned int GoUint32;
+typedef long long GoInt64;
+typedef unsigned long long GoUint64;
+typedef GoInt64 GoInt;
+typedef GoUint64 GoUint;
+typedef size_t GoUintptr;
+typedef float GoFloat32;
+typedef double GoFloat64;
+#ifdef _MSC_VER
+#include <complex.h>
+typedef _Fcomplex GoComplex64;
+typedef _Dcomplex GoComplex128;
+#else
+typedef float _Complex GoComplex64;
+typedef double _Complex GoComplex128;
+#endif
+
+/*
+  static assertion to make sure the file is being used on architecture
+  at least with matching size of GoInt.
+*/
+typedef char _check_for_64_bit_pointer_matching_GoInt[sizeof(void*)==64/8 ? 1:-1];
+
+#ifndef GO_CGO_GOSTRING_TYPEDEF
+typedef _GoString_ GoString;
+#endif
+typedef void *GoMap;
+typedef void *GoChan;
+typedef struct { void *t; void *v; } GoInterface;
+typedef struct { void *data; GoInt len; GoInt cap; } GoSlice;
+
+#endif
+
+/* End of boilerplate cgo prologue.  */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+extern int ProbeStart(char* knock);
+extern void ProbeStop();
+extern int ProbeRunning();
+extern char* ProbeLastError();
+
+#ifdef __cplusplus
+}
+#endif