@geek-fun/serverlessinsight 0.9.3 → 0.9.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +5 -2
- package/CHANGELOG.md +56 -0
- package/README.md +266 -179
- package/README.zh-CN.md +264 -147
- package/codecov +0 -0
- package/codecov.SHA256SUM +1 -1
- package/codecov.SHA256SUM.sig +13 -13
- package/dist/package.json +22 -19
- package/dist/src/commands/deploy.js +7 -2
- package/dist/src/commands/destroy.js +6 -3
- package/dist/src/commands/forceUnlock.js +16 -21
- package/dist/src/commands/index.js +26 -63
- package/dist/src/commands/migrate.js +105 -132
- package/dist/src/commands/plan.js +27 -3
- package/dist/src/commands/show.js +17 -6
- package/dist/src/common/aggregateState.js +185 -0
- package/dist/src/common/aggregateStore.js +247 -0
- package/dist/src/common/aliyunClient/apigwOperations.js +32 -9
- package/dist/src/common/apiClient.js +35 -12
- package/dist/src/common/constants.js +2 -1
- package/dist/src/common/context.js +22 -15
- package/dist/src/common/effectiveConfig.js +48 -0
- package/dist/src/common/index.js +5 -0
- package/dist/src/common/jsonOutput.js +2 -13
- package/dist/src/common/migrationMarker.js +0 -7
- package/dist/src/common/nameBuilder.js +2 -3
- package/dist/src/common/regionalMigration.js +261 -0
- package/dist/src/common/saasProtocol.js +41 -0
- package/dist/src/common/stateBackend/cosStateBackend.js +88 -8
- package/dist/src/common/stateBackend/index.js +42 -18
- package/dist/src/common/stateBackend/localStateBackend.js +61 -26
- package/dist/src/common/stateBackend/ossStateBackend.js +62 -9
- package/dist/src/common/stateBackend/remoteStateBackend.js +94 -94
- package/dist/src/common/stateBackend/saasStateBackend.js +327 -92
- package/dist/src/common/stateBackend/types.js +9 -0
- package/dist/src/common/stateManager.js +38 -11
- package/dist/src/common/stateScope.js +34 -0
- package/dist/src/common/stateStorageIO.js +31 -0
- package/dist/src/lang/en.js +48 -6
- package/dist/src/lang/index.js +28 -14
- package/dist/src/lang/zh-CN.js +48 -6
- package/dist/src/parser/index.js +25 -4
- package/dist/src/stack/aliyunStack/apigwDomainPlan.js +82 -0
- package/dist/src/stack/aliyunStack/apigwExecutor.js +4 -1
- package/dist/src/stack/aliyunStack/apigwPlanner.js +115 -55
- package/dist/src/stack/aliyunStack/apigwResource.js +169 -124
- package/dist/src/stack/aliyunStack/deployer.js +5 -5
- package/dist/src/stack/aliyunStack/destroyer.js +5 -5
- package/dist/src/stack/aliyunStack/fc3Planner.js +1 -1
- package/dist/src/stack/aliyunStack/fc3Resource.js +2 -2
- package/dist/src/stack/aliyunStack/planner.js +1 -1
- package/dist/src/stack/aliyunStack/sharedLogProject.js +2 -2
- package/dist/src/stack/ownershipTag.js +34 -26
- package/dist/src/stack/scfStack/deployer.js +5 -5
- package/dist/src/stack/scfStack/destroyer.js +5 -6
- package/dist/src/stack/scfStack/planner.js +1 -1
- package/dist/src/stack/scfStack/scfResource.js +1 -1
- package/dist/src/stack/scfStack/sharedLogset.js +5 -2
- package/dist/src/stack/volcengineStack/deployer.js +3 -3
- package/dist/src/stack/volcengineStack/destroyer.js +2 -3
- package/dist/src/stack/volcengineStack/planner.js +1 -1
- package/dist/src/stack/volcengineStack/sharedLogProject.js +4 -4
- package/dist/src/stack/volcengineStack/vefaasResource.js +1 -1
- package/dist/src/types/domains/state.js +28 -2
- package/dist/src/validator/rootSchema.js +8 -0
- package/dist/tsconfig.tsbuildinfo +1 -1
- package/package.json +22 -19
- package/release-notes.md +27 -56
- package/samples/README_TENCENT_COS.md +68 -26
- package/samples/README_TENCENT_SCF.md +47 -29
- package/.serverlessinsight/state-cdn-flow-app-cdn-flow-service.json.backup +0 -14
- package/.serverlessinsight/state-iam-test-app-iam-test-service.json.backup +0 -32
- package/.serverlessinsight/state-insight-poc-app-insight-poc-tencent.json.backup +0 -90
- package/.serverlessinsight/state-insight-poc-app-log-insight-poc-tencent-log.json.backup +0 -118
- package/.serverlessinsight/state-insight-poc-deploy-app-insight-poc-deploy.json.backup +0 -215
- package/.serverlessinsight/state-insight-poc-destroy-app-insight-poc-destroy.json.backup +0 -14
- package/.serverlessinsight/state-insight-poc-timer-app-insight-poc-timer.json.backup +0 -132
- package/.serverlessinsight/state-insight-volc-app-insight-volc.json.backup +0 -55
- package/.serverlessinsight/state-insight-volc-destroy-app-insight-volc-destroy.json.backup +0 -1
- package/.serverlessinsight/state-insight-volc-nested-app-insight-volc-nested.json.backup +0 -93
- package/.serverlessinsight/state-nested-drift-app-nested-drift-service.json.backup +0 -163
- package/.serverlessinsight/state-role-reconcile-test-app-role-reconcile-test-service.json.backup +0 -148
package/README.md
CHANGED
|
@@ -4,28 +4,30 @@
|
|
|
4
4
|
|
|
5
5
|
# ServerlessInsight
|
|
6
6
|
|
|
7
|
-
**Full
|
|
7
|
+
**Full-lifecycle serverless IaC for Alibaba Cloud, Tencent Cloud and Volcengine.**
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
**Serverless CLI for Alibaba Cloud · Tencent Cloud · Huawei Cloud · Volcengine.**
|
|
9
|
+
Define functions, API gateways, storage and databases in one YAML — preview the plan, deploy with confidence, and operate it in production.
|
|
12
10
|
|
|
13
11
|
[](https://github.com/geek-fun/serverlessinsight/releases)
|
|
14
12
|
[](https://www.npmjs.com/package/@geek-fun/serverlessinsight)
|
|
15
|
-
[](https://www.npmjs.com/package/@geek-fun/serverlessinsight)
|
|
14
|
+
[](LICENSE)
|
|
17
15
|
[](https://github.com/geek-fun/serverlessinsight/actions/workflows/node.yml)
|
|
16
|
+
[](https://github.com/geek-fun/serverlessinsight/stargazers)
|
|
17
|
+
[](https://github.com/geek-fun/serverlessinsight/issues)
|
|
18
|
+
|
|
19
|
+
<p>
|
|
20
|
+
<img src="https://img.shields.io/badge/Node.js-%3E%3D22.12-339933?logo=nodedotjs&logoColor=white" alt="Node.js >= 22.12" />
|
|
21
|
+
<img src="https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white" alt="TypeScript" />
|
|
22
|
+
</p>
|
|
18
23
|
|
|
19
24
|
<p>
|
|
20
|
-
<img src="https://img.shields.io/badge/
|
|
21
|
-
<img src="https://img.shields.io/badge/
|
|
22
|
-
<img src="https://img.shields.io/badge/
|
|
23
|
-
<img src="https://img.shields.io/badge/Tencent%20Cloud-0A9AED&logo=tencentqq&logoColor=white"/>
|
|
24
|
-
<img src="https://img.shields.io/badge/Huawei%20Cloud-FF0000?logo=huawei&logoColor=white"/>
|
|
25
|
-
<img src="https://img.shields.io/badge/AWS-232F3E&logo=amazonwebservices&logoColor=white"/>
|
|
25
|
+
<img src="https://img.shields.io/badge/Alibaba%20Cloud-FF6A00?logo=alibabacloud&logoColor=white" alt="Alibaba Cloud" />
|
|
26
|
+
<img src="https://img.shields.io/badge/Tencent%20Cloud-0A9AED?logo=tencentqq&logoColor=white" alt="Tencent Cloud" />
|
|
27
|
+
<img src="https://img.shields.io/badge/Volcengine-1677FF?logoColor=white" alt="Volcengine" />
|
|
26
28
|
</p>
|
|
27
29
|
|
|
28
|
-
[npm](https://www.npmjs.com/package/@geek-fun/serverlessinsight) · [
|
|
30
|
+
[npm](https://www.npmjs.com/package/@geek-fun/serverlessinsight) · [Documentation](https://serverlessinsight.com/docs.html) · [Website](https://serverlessinsight.com) · [Samples](samples) · [Changelog](CHANGELOG.md) · [Issues](https://github.com/geek-fun/serverlessinsight/issues)
|
|
29
31
|
|
|
30
32
|
English · [简体中文](README.zh-CN.md)
|
|
31
33
|
|
|
@@ -33,151 +35,195 @@ English · [简体中文](README.zh-CN.md)
|
|
|
33
35
|
|
|
34
36
|
---
|
|
35
37
|
|
|
36
|
-
ServerlessInsight is
|
|
38
|
+
ServerlessInsight (`si`) is an open-source, cross-cloud serverless framework. Instead of juggling provider-specific CLIs, console clicks and one-off scripts, you describe the whole serverless stack — functions, HTTP endpoints, object storage, databases and tables — in a single YAML file, then let `si` plan, deploy and operate it.
|
|
37
39
|
|
|
38
|
-
|
|
39
|
-
<img src="https://img.shields.io/badge/Alibaba%20Cloud-FF6A00?logo=alibabacloud&logoColor=white" />
|
|
40
|
-
<img src="https://img.shields.io/badge/Tencent%20Cloud-0A9AED?logo=tencentqq&logoColor=white" />
|
|
41
|
-
<img src="https://img.shields.io/badge/Huawei%20Cloud-FF0000?logo=huawei&logoColor=white" />
|
|
42
|
-
<img src="https://img.shields.io/badge/Volcengine-1677FF?logoColor=white" />
|
|
43
|
-
<img src="https://img.shields.io/badge/AWS-232F3E?logo=amazonwebservices&logoColor=white" />
|
|
44
|
-
<img src="https://img.shields.io/badge/Azure-0078D4?logo=microsoftazure&logoColor=white" />
|
|
45
|
-
<img src="https://img.shields.io/badge/GCP-4285F4?logo=googlecloud&logoColor=white" />
|
|
46
|
-
</p>
|
|
40
|
+
Think Terraform for serverless: one declarative workflow with state tracking and drift detection, built around functions, API gateways and serverless data services. No vendor lock-in, Apache-2.0 licensed.
|
|
47
41
|
|
|
48
|
-
|
|
42
|
+
**Deployable today:** Alibaba Cloud, Tencent Cloud and Volcengine. Huawei Cloud, AWS, Azure and Google Cloud are on the [roadmap](#roadmap).
|
|
43
|
+
|
|
44
|
+
## Table of contents
|
|
45
|
+
|
|
46
|
+
- [Quick start](#quick-start)
|
|
47
|
+
- [Why ServerlessInsight](#why-serverlessinsight)
|
|
48
|
+
- [Features](#features)
|
|
49
|
+
- [Supported providers](#supported-providers)
|
|
50
|
+
- [Documentation](#documentation)
|
|
51
|
+
- [Roadmap](#roadmap)
|
|
52
|
+
- [Architecture](#architecture)
|
|
53
|
+
- [Development](#development)
|
|
54
|
+
- [Community](#community)
|
|
55
|
+
- [Contributing](#contributing)
|
|
56
|
+
- [Sponsor](#sponsor)
|
|
57
|
+
- [License](#license)
|
|
58
|
+
|
|
59
|
+
## Quick start
|
|
60
|
+
|
|
61
|
+
**Requires Node.js 22.12 or later.**
|
|
49
62
|
|
|
50
63
|
```bash
|
|
51
64
|
npm install -g @geek-fun/serverlessinsight
|
|
52
65
|
si --version
|
|
53
66
|
```
|
|
54
67
|
|
|
55
|
-
|
|
68
|
+
Create `serverlessinsight.yml`:
|
|
56
69
|
|
|
57
|
-
|
|
70
|
+
```yaml
|
|
71
|
+
version: 0.0.1
|
|
72
|
+
|
|
73
|
+
provider:
|
|
74
|
+
name: aliyun
|
|
75
|
+
region: cn-hongkong
|
|
58
76
|
|
|
59
|
-
|
|
77
|
+
app: hello-world
|
|
78
|
+
service: hello-world-api
|
|
79
|
+
|
|
80
|
+
functions:
|
|
81
|
+
hello_function:
|
|
82
|
+
name: hello-world-fn
|
|
83
|
+
code:
|
|
84
|
+
runtime: nodejs18
|
|
85
|
+
handler: index.handler
|
|
86
|
+
path: ./src
|
|
87
|
+
memory: 512
|
|
88
|
+
timeout: 10
|
|
60
89
|
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
90
|
+
events:
|
|
91
|
+
api_gateway:
|
|
92
|
+
type: API_GATEWAY
|
|
93
|
+
name: my-api-gateway
|
|
94
|
+
triggers:
|
|
95
|
+
- method: GET
|
|
96
|
+
path: /api/hello
|
|
97
|
+
backend: ${functions.hello_function}
|
|
98
|
+
```
|
|
64
99
|
|
|
65
|
-
|
|
66
|
-
| ----------------- | ---------------- | -------------- | -------------- | ---------------- | ------- |
|
|
67
|
-
| **Alibaba Cloud** | ✅ FC3 | ✅ API Gateway | ✅ OSS | ✅ RDS, OTS, ESS | Stable |
|
|
68
|
-
| **Tencent Cloud** | ✅ SCF | 🚧 Coming Soon | ✅ COS | ✅ TDSQL-C | Stable |
|
|
69
|
-
| **Volcengine** | ✅ veFaaS | ✅ API Gateway | ✅ TOS | — | Stable |
|
|
70
|
-
| **Huawei Cloud** | 🚧 Coming Soon | 🚧 Coming Soon | 🚧 Coming Soon | 🚧 Coming Soon | Planned |
|
|
71
|
-
| **AWS** | 🔜 Planned | 🔜 Planned | 🔜 Planned | 🔜 Planned | Planned |
|
|
72
|
-
| **Azure** | 🔜 Planned | 🔜 Planned | 🔜 Planned | 🔜 Planned | Planned |
|
|
73
|
-
| **Google Cloud** | 🔜 Planned | 🔜 Planned | 🔜 Planned | 🔜 Planned | Planned |
|
|
100
|
+
Then:
|
|
74
101
|
|
|
75
|
-
|
|
102
|
+
```bash
|
|
103
|
+
si validate # check the config against the IaC schema
|
|
104
|
+
si diff # show what would change, without saving state
|
|
105
|
+
si deploy --stage prod # show the plan, confirm, and apply
|
|
106
|
+
si local # run the app locally on http://localhost:4567
|
|
107
|
+
si destroy --stage prod # remove everything si created
|
|
108
|
+
```
|
|
76
109
|
|
|
77
|
-
|
|
110
|
+
`si` discovers `serverlessinsight.yml` in the current directory; pass `-f <path>` for a different file name. To target another cloud, select `-v tencent` or `-v volcengine` with a valid region and a compatible resource configuration. The override selects an independent deployment; adapt unsupported runtimes or resources before deploying.
|
|
78
111
|
|
|
79
|
-
|
|
80
|
-
- **State tracking** — incremental deployments with drift detection via local state files
|
|
81
|
-
- **Validation** — type-safe template validation catches config errors before they reach the cloud
|
|
82
|
-
- **Partial failure recovery** — successfully deployed resources are saved even when others fail; retry to continue
|
|
112
|
+
## Why ServerlessInsight
|
|
83
113
|
|
|
84
|
-
|
|
114
|
+
- **Serverless-native, not generic IaC.** Functions, triggers, API gateways, domains, buckets, databases and tables are first-class resources with provider-aware defaults — no hand-written Terraform modules or SDK wrapper scripts.
|
|
115
|
+
- **One configuration format across clouds.** Reuse supported primitives and stage variables across providers; validate each target configuration before deploying.
|
|
116
|
+
- **Plan before anything happens.** `si diff` reads state and live resources without writing anything; `si deploy` executes exactly the plan you approved, and manual console changes surface as drift.
|
|
117
|
+
- **Built for automation.** Logs go to stderr and machine-readable results to stdout, every JSON envelope is versioned, error codes are stable across locales, and exit codes follow Terraform conventions.
|
|
118
|
+
- **Real local development.** Run your handlers, HTTP routes, timer schedules and bucket endpoints locally with the same configuration — no cloud account or credentials needed.
|
|
119
|
+
- **Open source, no lock-in.** Apache-2.0, state in a local file or your own bucket, and no proprietary runtime to adopt.
|
|
85
120
|
|
|
86
|
-
|
|
87
|
-
# Validate your config
|
|
88
|
-
si validate -f serverless.yml
|
|
121
|
+
## Features
|
|
89
122
|
|
|
90
|
-
|
|
91
|
-
si plan -f serverless.yml
|
|
123
|
+
### Multi-cloud, one config
|
|
92
124
|
|
|
93
|
-
|
|
94
|
-
si deploy -f serverless.yml -s prod
|
|
125
|
+
Use one configuration format across Alibaba Cloud, Tencent Cloud and Volcengine. Shared mappings handle supported provider differences; each target must support the declared runtimes and resources.
|
|
95
126
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
127
|
+
- **Unified configuration** — one `serverlessinsight.yml` format for every provider
|
|
128
|
+
- **Provider-specific mapping** — runtime names, trigger shapes and resource types are translated to native values
|
|
129
|
+
- **Cross-provider validation** — unsupported target resources fail before cloud execution
|
|
99
130
|
|
|
100
|
-
###
|
|
131
|
+
### Plan before deploy
|
|
101
132
|
|
|
102
|
-
`si
|
|
103
|
-
and Volcengine. Volcengine plans include functions, TOS buckets, and API Gateway
|
|
104
|
-
resources in dependency order. Planning reads the configured state backend and
|
|
105
|
-
cloud resources without applying changes or saving state.
|
|
133
|
+
`si diff` previews every change on Alibaba Cloud, Tencent Cloud and Volcengine. It reads the configured state backend and live cloud resources without applying changes or saving state.
|
|
106
134
|
|
|
107
135
|
```bash
|
|
108
|
-
si
|
|
109
|
-
si diff
|
|
110
|
-
si
|
|
111
|
-
si diff
|
|
136
|
+
si diff --stage dev
|
|
137
|
+
si diff --stage dev --json
|
|
138
|
+
si diff --stage dev --region cn-beijing -p memory=1024
|
|
139
|
+
si diff --stage dev --no-refresh
|
|
112
140
|
```
|
|
113
141
|
|
|
114
|
-
Use `-p, --parameter <key=value>` repeatedly to override configuration variables.
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
configured. Read failures exit with an error. Migrated legacy state produces a
|
|
118
|
-
warning and remains unchanged.
|
|
142
|
+
Use `-p, --parameter <key=value>` repeatedly to override configuration variables. `--no-refresh` skips live drift checks for tracked resources; ownership probes for new resources still run. Credentials and the selected state backend must be configured. Read failures exit with an error. Migrated legacy state produces a warning and remains unchanged.
|
|
143
|
+
|
|
144
|
+
Volcengine plans include functions, TOS buckets and API Gateway resources in dependency order.
|
|
119
145
|
|
|
120
|
-
|
|
146
|
+
**Exit codes**: `si diff` exits `0` when there are no changes, `2` when changes are present (Terraform convention), and `1` on errors. `si validate` exits `0` when valid and `1` when validation fails.
|
|
121
147
|
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
148
|
+
### Independent provider and region deployments
|
|
149
|
+
|
|
150
|
+
Deployment identity is `Org / App / Service / Stage / Provider / Region`.
|
|
151
|
+
`app` and `service` stay literal in YAML; `-s`, `-v` and `-r` select one deployment.
|
|
152
|
+
A compatible YAML can be reused, or separate YAML files can describe different regional
|
|
153
|
+
resources. Selecting the same scope and backend location addresses the same deployment.
|
|
154
|
+
Changing provider/region creates or updates the selected deployment and preserves the
|
|
155
|
+
previous deployment until an explicitly scoped destroy. Provider-specific declarations
|
|
156
|
+
must be supported by the target cloud; overrides do not translate unsupported resources.
|
|
157
|
+
|
|
158
|
+
Local state stays at `.serverlessinsight/state-<app>-<service>.json`; Bucket Store keeps
|
|
159
|
+
the exact configured `key`. Both store a V4 aggregate partitioned by stage/provider/region
|
|
160
|
+
under one whole-file lock. Executors and SaaS snapshots use a single-deployment V4 view;
|
|
161
|
+
SaaS mutations require scope protocol 3. Cloud accounts remain credential context rather
|
|
162
|
+
than another identity dimension.
|
|
163
|
+
|
|
164
|
+
See [deployment state and migration](docs/regional-deployment-state.md) for storage
|
|
165
|
+
credentials, automatic V3 upgrades, ownership handoff, lock behavior and recovery.
|
|
166
|
+
|
|
167
|
+
### Infrastructure as code
|
|
168
|
+
|
|
169
|
+
Declarative YAML with validation, planning and state management, following proven IaC patterns.
|
|
170
|
+
|
|
171
|
+
- **State tracking** — incremental deployments from `.serverlessinsight/` state, with local, bucket and SaaS backends
|
|
172
|
+
- **Drift detection** — resources changed outside `si` are flagged before the next deploy
|
|
173
|
+
- **Validation** — type-safe template validation catches config errors before they reach the cloud
|
|
174
|
+
- **Partial failure recovery** — successfully deployed resources are saved even when others fail; retry to continue
|
|
175
|
+
- **State locking** — concurrent deploys are blocked, with `si force-unlock` as the escape hatch
|
|
176
|
+
|
|
177
|
+
### Built for agents and scripts
|
|
178
|
+
|
|
179
|
+
The CLI is designed to be driven by agents and shell scripts: logs always go to **stderr** while result data goes to **stdout**, so piping stdout into `jq` always yields a single parseable JSON document.
|
|
125
180
|
|
|
126
181
|
```bash
|
|
127
|
-
si
|
|
128
|
-
si validate --json
|
|
129
|
-
si show --json
|
|
130
|
-
si schema | jq '
|
|
182
|
+
si diff --json | jq '.summary'
|
|
183
|
+
si validate --json | jq '.valid'
|
|
184
|
+
si show --json | jq '.resourceCount'
|
|
185
|
+
si schema | jq '."$id"' # self-contained draft-07 JSON Schema of the IaC format
|
|
131
186
|
```
|
|
132
187
|
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
- `si
|
|
141
|
-
keyword, message, allowedValues? }] }`
|
|
142
|
-
- `si show --json` → `{ showVersion: 1, provider, app, service, stage,
|
|
143
|
-
stateLocation, backend: "saas|bucket_store|local", locked, lock, resources,
|
|
144
|
-
resourceCount, ... }`
|
|
188
|
+
<details>
|
|
189
|
+
<summary><b>Stable output envelopes, error codes and color behavior</b></summary>
|
|
190
|
+
|
|
191
|
+
Stable output envelopes (each carries a version field, so shapes only ever change under a new version):
|
|
192
|
+
|
|
193
|
+
- `si diff --json` → `{ planVersion: 2, provider, app, service, stage, region, changes: [{ logicalId, type, action: "create|update|destroy|recreate", attributes, drifted?, driftReasons? }], summary: { create, update, destroy, recreate, unchanged } }`
|
|
194
|
+
- `si validate --json` → `{ validateVersion: 1, valid, errors: [{ path, keyword, message, allowedValues? }] }`
|
|
195
|
+
- `si show --json` → `{ showVersion: 2, provider, app, service, stage, region, stateLocation, backend: "saas|bucket_store|local", locked, lock, resources, resourceCount, ... }`
|
|
145
196
|
- failures (in `--json` mode) → `{ error: { code, message } }` on stdout
|
|
146
197
|
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
198
|
+
Stable error codes: error `code`s are the i18n message keys behind the translated message (e.g. `RAM_ROLE_NOT_FOUND_IN_CLOUD`) — they are identical under every locale, so agents can map codes to self-healing actions regardless of `LANG`.
|
|
199
|
+
|
|
200
|
+
Colors: ANSI color is disabled when the `NO_COLOR` environment variable is set ([no-color.org](https://no-color.org)) or `--no-color` is passed, keeping piped output clean in non-TTY environments.
|
|
150
201
|
|
|
151
|
-
|
|
152
|
-
translated message (e.g. `RAM_ROLE_NOT_FOUND_IN_CLOUD`) — they are identical
|
|
153
|
-
under every locale, so agents can map codes to self-healing actions regardless
|
|
154
|
-
of `LANG`.
|
|
202
|
+
</details>
|
|
155
203
|
|
|
156
|
-
|
|
157
|
-
set ([no-color.org](https://no-color.org)) or `--no-color` is passed, keeping
|
|
158
|
-
piped output clean in non-TTY environments.
|
|
204
|
+
### Local development
|
|
159
205
|
|
|
160
|
-
|
|
206
|
+
Run and debug serverless functions locally without deploying to the cloud or configuring credentials.
|
|
161
207
|
|
|
162
|
-
|
|
208
|
+
- **HTTP functions** — provider-native event, context and response translation for Aliyun FC, Tencent SCF function URLs and Volcengine veFaaS
|
|
209
|
+
- **Timer triggers** — `functions.*.triggers.timer` schedules fire against UTC wall-clock and invoke your handler with the provider's timer event shape
|
|
210
|
+
- **Bucket file serving** — access local storage files over HTTP for rapid iteration
|
|
211
|
+
- **Watch mode** — code changes reload automatically
|
|
212
|
+
- **Same config, different target** — `si local -s dev` reuses your existing configuration
|
|
163
213
|
|
|
164
|
-
-
|
|
165
|
-
- **Timer triggers fire locally** — Aliyun, Tencent and Volcengine `functions.*.triggers.timer` schedules run against UTC wall-clock (`@every` from server start) and invoke your handler with the provider's timer event shape
|
|
166
|
-
- **Volcengine HTTP invocation** — veFaaS Node.js events, context and response translation for the [documented local subset](docs/local-development.md), with a [runnable example](samples/volcengine-local/serverlessinsight.yml)
|
|
167
|
-
- **Tencent SCF HTTP invocation** — SCF function-URL events, native context and response translation for `nodejs10`–`nodejs18` packages, with a [runnable example](samples/tencent-local/serverlessinsight.yml)
|
|
168
|
-
- **Bucket file serving** — access local storage files via HTTP for rapid iteration
|
|
169
|
-
- **Same config, different target** — `si local -f serverless.yml -s local` uses your existing config
|
|
214
|
+
See [Local development](docs/local-development.md) for the supported subset and runnable examples: [Tencent SCF](samples/tencent-local/serverlessinsight.yml) and [Volcengine veFaaS](samples/volcengine-local/serverlessinsight.yml).
|
|
170
215
|
|
|
171
|
-
### API
|
|
216
|
+
### API gateway & custom domains
|
|
172
217
|
|
|
173
218
|
Configure HTTP endpoints and bind custom domains with automatic DNS verification.
|
|
174
219
|
|
|
175
|
-
- **
|
|
176
|
-
- **Custom
|
|
220
|
+
- **HTTP triggers** — define triggers with HTTP methods and paths, backed by a function
|
|
221
|
+
- **Custom domains** — automatic CNAME + DNS TXT ownership verification for OSS and API Gateway on Alibaba Cloud, and DNSPod-backed domains on Tencent Cloud
|
|
177
222
|
- **CDN acceleration** — edge caching and global content delivery for static sites
|
|
178
|
-
- **OSS
|
|
223
|
+
- **OSS transfer acceleration** — cross-region data transfers through the Alibaba backbone
|
|
224
|
+
- **Tencent function URLs** — HTTP entry points without a standalone gateway resource
|
|
179
225
|
|
|
180
|
-
### Timer
|
|
226
|
+
### Timer triggers
|
|
181
227
|
|
|
182
228
|
Schedule functions with a provider-agnostic `si-cron` expression under `functions.*.triggers.timer`:
|
|
183
229
|
|
|
@@ -195,33 +241,70 @@ functions:
|
|
|
195
241
|
cron: '@every 1h'
|
|
196
242
|
```
|
|
197
243
|
|
|
198
|
-
`cron` accepts a standard 5-field expression (`minute hour day month weekday`),
|
|
199
|
-
a 6-field expression with a seconds prefix, or `@every <duration>` (`30s`,
|
|
200
|
-
`5m`, `1h`, `1d`, …). si-cron is always **UTC** — the synthesis layer
|
|
201
|
-
translates it into each provider's dialect (Aliyun FC3 6-field, Tencent SCF
|
|
202
|
-
7-field with year, Volcengine veFaaS 5-field crontab) including the UTC+8
|
|
203
|
-
field shift, so the same YAML fires at the same instant everywhere. Invalid
|
|
204
|
-
expressions and provider capability limits (Tencent SCF allows at most 10
|
|
205
|
-
timers per function) fail at `si validate`, before any deploy.
|
|
244
|
+
`cron` accepts a standard 5-field expression (`minute hour day month weekday`), a 6-field expression with a seconds prefix, or `@every <duration>` (`30s`, `5m`, `1h`, `1d`, …). si-cron is always **UTC** — the synthesis layer translates it into each provider's dialect (Aliyun FC3 6-field, Tencent SCF 7-field with year, Volcengine veFaaS 5-field crontab), including the UTC+8 field shift, so the same YAML fires at the same instant everywhere. Invalid expressions and provider capability limits (Tencent SCF allows at most 10 timers per function) fail at `si validate`, before any deploy.
|
|
206
245
|
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
the function, and have no independent configuration surface. Top-level
|
|
210
|
-
`events` (e.g. `API_GATEWAY`) are infrastructure resources with their own
|
|
211
|
-
config face — custom domains, certificates, route tables — that keep living
|
|
212
|
-
when a backend function is removed. Rule of thumb: independent
|
|
213
|
-
configuration surface → `events`; pure scheduling/event binding → `triggers`.
|
|
246
|
+
<details>
|
|
247
|
+
<summary><b><code>triggers</code> vs top-level <code>events</code></b></summary>
|
|
214
248
|
|
|
215
|
-
|
|
249
|
+
`functions.*.triggers` (http, timer) are things that *invoke this function* — they are function-owned, die with the function, and have no independent configuration surface. Top-level `events` (e.g. `API_GATEWAY`) are infrastructure resources with their own config face — custom domains, certificates, route tables — that keep living when a backend function is removed. Rule of thumb: independent configuration surface → `events`; pure scheduling/event binding → `triggers`.
|
|
216
250
|
|
|
217
|
-
|
|
251
|
+
</details>
|
|
218
252
|
|
|
219
|
-
|
|
220
|
-
- **Databases** — RDS, OTS, ESS, TDSQL-C with more on the way
|
|
221
|
-
- **Elasticsearch Serverless** — deploy and manage ES clusters
|
|
222
|
-
- **GPU functions** — deploy GPU-enabled serverless functions
|
|
253
|
+
### Resource management
|
|
223
254
|
|
|
224
|
-
|
|
255
|
+
Beyond functions — manage the full serverless stack, including storage, databases and tables.
|
|
256
|
+
|
|
257
|
+
- **Object storage** — OSS (Alibaba), COS (Tencent), TOS (Volcengine)
|
|
258
|
+
- **Databases** — RDS MySQL Serverless, TDSQL-C and Elasticsearch Serverless
|
|
259
|
+
- **Tables** — TableStore on Alibaba Cloud
|
|
260
|
+
- **GPU functions** — deploy GPU-enabled serverless functions on Alibaba Cloud
|
|
261
|
+
|
|
262
|
+
## Supported providers
|
|
263
|
+
|
|
264
|
+
| Provider | Functions | HTTP entry | Object storage | Databases & tables | Status |
|
|
265
|
+
| ----------------- | ---------------------------- | ------------------------- | -------------- | ----------------------------------------------------------- | ------- |
|
|
266
|
+
| **Alibaba Cloud** | ✅ FC3 | ✅ API Gateway | ✅ OSS | ✅ RDS MySQL Serverless, TableStore, Elasticsearch Serverless | Stable |
|
|
267
|
+
| **Tencent Cloud** | ✅ SCF | ✅ Function URL triggers | ✅ COS | ✅ TDSQL-C, Elasticsearch Serverless | Stable |
|
|
268
|
+
| **Volcengine** | ✅ veFaaS | ✅ API Gateway | ✅ TOS | — | Stable |
|
|
269
|
+
| **Huawei Cloud** | ⚠️ Terraform template only | — | — | — | Preview |
|
|
270
|
+
| **AWS** | — | — | — | — | Planned |
|
|
271
|
+
| **Azure** | — | — | — | — | Planned |
|
|
272
|
+
| **Google Cloud** | — | — | — | — | Planned |
|
|
273
|
+
|
|
274
|
+
Notes:
|
|
275
|
+
|
|
276
|
+
- Huawei Cloud configuration is parsed and can generate Terraform HCL templates, but deployment is not implemented yet.
|
|
277
|
+
- Tencent Cloud has no standalone API Gateway resource; HTTP entry points use function URL triggers.
|
|
278
|
+
- Volcengine does not yet support serverless databases or tables.
|
|
279
|
+
- See the [full provider matrix](https://serverlessinsight.com/reference.html) for resource-level details.
|
|
280
|
+
|
|
281
|
+
## Documentation
|
|
282
|
+
|
|
283
|
+
| Resource | Link |
|
|
284
|
+
| ------------------------- | --------------------------------------------------------------------- |
|
|
285
|
+
| Getting started | <https://serverlessinsight.com/getting-started.html> |
|
|
286
|
+
| Configuration reference | <https://serverlessinsight.com/reference.html> |
|
|
287
|
+
| CLI reference | <https://serverlessinsight.com/cli.html> |
|
|
288
|
+
| JSON Schema | `si schema` (self-contained draft-07) |
|
|
289
|
+
| Local development | [docs/local-development.md](docs/local-development.md) |
|
|
290
|
+
| Deployment state | [docs/regional-deployment-state.md](docs/regional-deployment-state.md) |
|
|
291
|
+
| State locking | [docs/state-locking.md](docs/state-locking.md) |
|
|
292
|
+
| Architecture decisions | [docs/adr](docs/adr) |
|
|
293
|
+
| Samples | [samples](samples) |
|
|
294
|
+
| Changelog | [CHANGELOG.md](CHANGELOG.md) |
|
|
295
|
+
| FAQ | <https://serverlessinsight.com/faq.html> |
|
|
296
|
+
|
|
297
|
+
## Roadmap
|
|
298
|
+
|
|
299
|
+
- Huawei Cloud function deployment (template generation exists today)
|
|
300
|
+
- AWS, Azure and Google Cloud providers
|
|
301
|
+
- Tencent Cloud standalone API Gateway resources
|
|
302
|
+
- Volcengine serverless databases and tables
|
|
303
|
+
- More serverless resources and provider capabilities
|
|
304
|
+
|
|
305
|
+
Roadmap items are directional, not commitments. Open an issue to discuss priorities.
|
|
306
|
+
|
|
307
|
+
## Architecture
|
|
225
308
|
|
|
226
309
|
ServerlessInsight follows a **functional client architecture** that cleanly separates cloud provider SDKs from business logic:
|
|
227
310
|
|
|
@@ -233,27 +316,29 @@ ServerlessInsight follows a **functional client architecture** that cleanly sepa
|
|
|
233
316
|
↓
|
|
234
317
|
┌─────────────────────────────────────────┐
|
|
235
318
|
│ Functional Client Layer │ ← Encapsulated SDK operations
|
|
236
|
-
│
|
|
319
|
+
│ (aliyunClient, tencentClient, │
|
|
320
|
+
│ volcengineClient) │
|
|
237
321
|
└─────────────────────────────────────────┘
|
|
238
322
|
↓
|
|
239
323
|
┌─────────────────────────────────────────┐
|
|
240
|
-
│ Cloud Provider SDKs │ ← @alicloud/*, tencentcloud
|
|
324
|
+
│ Cloud Provider SDKs │ ← @alicloud/*, tencentcloud-*, @volcengine/*
|
|
241
325
|
└─────────────────────────────────────────┘
|
|
242
326
|
```
|
|
243
327
|
|
|
244
|
-
- **Functional
|
|
245
|
-
- **SDK encapsulation** — provider SDKs accessed
|
|
246
|
-
- **
|
|
328
|
+
- **Functional and pure** — business logic uses pure functions with immutable data
|
|
329
|
+
- **SDK encapsulation** — provider SDKs are accessed only through client modules
|
|
330
|
+
- **Functional-first** — `type` over `interface`, functions over classes, declarative collection handling
|
|
247
331
|
|
|
248
332
|
## Development
|
|
249
333
|
|
|
250
|
-
ServerlessInsight is built with [Node.js](https://nodejs.org/) + [TypeScript](https://www.typescriptlang.org/), [Commander.js](https://github.com/tj/commander.js/) CLI, and
|
|
334
|
+
ServerlessInsight is built with [Node.js](https://nodejs.org/) + [TypeScript](https://www.typescriptlang.org/), [Commander.js](https://github.com/tj/commander.js/) for the CLI, and a functional architecture.
|
|
251
335
|
|
|
252
336
|
### Prerequisites
|
|
253
337
|
|
|
254
|
-
- **Node.js** >=
|
|
338
|
+
- **Node.js** >= 22.12
|
|
339
|
+
- **npm** (bundled with Node.js)
|
|
255
340
|
|
|
256
|
-
###
|
|
341
|
+
### Build from source
|
|
257
342
|
|
|
258
343
|
```bash
|
|
259
344
|
git clone https://github.com/geek-fun/serverlessinsight.git
|
|
@@ -265,46 +350,44 @@ npm link
|
|
|
265
350
|
|
|
266
351
|
### Scripts
|
|
267
352
|
|
|
268
|
-
| Command
|
|
269
|
-
|
|
270
|
-
| `npm run build`
|
|
271
|
-
| `npm test`
|
|
272
|
-
| `npm run test:unit`
|
|
273
|
-
| `npm run test:service` | Service tests only
|
|
274
|
-
| `npm run
|
|
275
|
-
| `npm run lint:
|
|
276
|
-
|
|
277
|
-
### Sample Config
|
|
278
|
-
|
|
279
|
-
```yaml
|
|
280
|
-
version: 0.0.1
|
|
281
|
-
provider:
|
|
282
|
-
name: aliyun
|
|
283
|
-
region: cn-hongkong
|
|
353
|
+
| Command | Description |
|
|
354
|
+
| ---------------------- | ---------------------------- |
|
|
355
|
+
| `npm run build` | TypeScript compilation |
|
|
356
|
+
| `npm test` | All tests with coverage |
|
|
357
|
+
| `npm run test:unit` | Unit tests only |
|
|
358
|
+
| `npm run test:service` | Service tests only |
|
|
359
|
+
| `npm run test:ci` | CI test run |
|
|
360
|
+
| `npm run lint:check` | ESLint check |
|
|
361
|
+
| `npm run lint:fix` | Auto-fix lint issues |
|
|
284
362
|
|
|
285
|
-
service
|
|
363
|
+
Tests are split into fast, fully mocked unit tests and service tests that exercise the real parser, planner, executor and state manager. Coverage is enforced at 85% for branches, functions, lines and statements.
|
|
286
364
|
|
|
287
|
-
|
|
288
|
-
hello_function:
|
|
289
|
-
name: hello-world-fn
|
|
290
|
-
code:
|
|
291
|
-
runtime: nodejs18
|
|
292
|
-
handler: index.handler
|
|
293
|
-
path: ./src
|
|
294
|
-
memory: 512
|
|
295
|
-
timeout: 10
|
|
365
|
+
### Project structure
|
|
296
366
|
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
367
|
+
```
|
|
368
|
+
src/
|
|
369
|
+
├── commands/ # CLI command handlers (deploy, destroy, diff, local, ...)
|
|
370
|
+
├── common/ # Shared utilities, clients, state and lock management
|
|
371
|
+
│ ├── aliyunClient/
|
|
372
|
+
│ ├── tencentClient/
|
|
373
|
+
│ └── volcengineClient/
|
|
374
|
+
├── lang/ # i18n translations (en.ts, zh-CN.ts)
|
|
375
|
+
├── parser/ # YAML parsing and validation
|
|
376
|
+
├── stack/ # Provider-specific resource logic
|
|
377
|
+
│ ├── aliyunStack/
|
|
378
|
+
│ ├── scfStack/ # Tencent Cloud
|
|
379
|
+
│ ├── volcengineStack/
|
|
380
|
+
│ ├── localStack/ # Local development server
|
|
381
|
+
│ └── rfsStack/ # Huawei Cloud Terraform templates (preview)
|
|
382
|
+
├── types/ # TypeScript type definitions
|
|
383
|
+
└── validator/ # JSON Schema validation
|
|
384
|
+
tests/
|
|
385
|
+
├── fixtures/ # Test fixtures (YAML configs, artifacts)
|
|
386
|
+
├── unit/ # Isolated unit tests
|
|
387
|
+
└── service/ # End-to-end service tests
|
|
305
388
|
```
|
|
306
389
|
|
|
307
|
-
|
|
390
|
+
See [AGENTS.md](AGENTS.md) for coding conventions, test rules and architecture principles.
|
|
308
391
|
|
|
309
392
|
## Community
|
|
310
393
|
|
|
@@ -322,7 +405,11 @@ More in the [samples](./samples) directory.
|
|
|
322
405
|
|
|
323
406
|
## Contributing
|
|
324
407
|
|
|
325
|
-
Contributions welcome
|
|
408
|
+
Contributions are welcome — bug reports, feature requests, documentation fixes and code.
|
|
409
|
+
|
|
410
|
+
- Open an issue with the [bug report](.github/ISSUE_TEMPLATE/bug_report.md) or [feature request](.github/ISSUE_TEMPLATE/feature_request.md) template.
|
|
411
|
+
- Before opening a pull request, run `npm run lint:check`, `npm run build` and `npm test`.
|
|
412
|
+
- Follow the conventions in [AGENTS.md](AGENTS.md) and the existing [pull request template](.github/PULL_REQUEST_TEMPLATE.md).
|
|
326
413
|
|
|
327
414
|
## Sponsor
|
|
328
415
|
|