docs: consolidate runnable examples and publish v0.1.1 guides

examples/application-resources/README.md

@@ -0,0 +1,31 @@
+# 跨命名空间共享额度
+
+同一应用下两个命名空间共享上限，释放后原身份重报，并恢复配置。
+
+## 准备
+
+- Go 1.27.1、当前版本 Orbit；服务启动和初始化见[仓库 README](../../README.md#快速开始)。
+- 须按详细手册创建同一专用应用下的两个命名空间，两个凭据均增加 --resource-access。不能直接使用单份快速开始凭据。
+- [示例总索引](../README.md)提供统一初始化和权限说明；完整字段、失败处理见[详细手册](../../docs/api/application-resources.md)。
+
+## 运行
+
+以下命令从仓库根目录执行；凭据路径替换为实际初始化输出。
+
+```sh
+cd examples
+export ORBIT_URL=http://127.0.0.1:8080
+export ORBIT_CREDENTIALS_FILE="$PWD/../.local/app-first.credentials.json"
+export ORBIT_SECOND_CREDENTIALS_FILE="$PWD/../.local/app-second.credentials.json"
+go run ./application-resources
+```
+
+## 结果核对
+
+cross_namespace_backpressure=APPLICATION_FULL http=429；same_identity_retry_accepted=true；unfinished=0。具体 ID 和统计值以本次运行为准。程序会核对上述关键条件，失败时打印错误并以非零状态退出。
+
+## 接入自己的项目
+
+阅读[main.go](main.go)中的客户端创建、请求及错误处理。业务项目通过 `go get git.yuntuo.hk/k2safe/orbit/sdk/go@v0.1.1` 引入 SDK，无需导入本示例包。
+
+示例运行会写入真实平台数据，应使用专用测试应用/队列。正常结束保留历史和审计；重复演示通常创建新身份，不能当作上次失败操作的恢复。真实业务应在第一次请求前持久化操作身份，网络结果不明时沿原身份核对。

examples/application-resources/main.go

@@ -0,0 +1,101 @@
+// application-resources 演示同一应用的两个命名空间共享积压额度。
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"time"
+
+	orbit "git.yuntuo.hk/k2safe/orbit/sdk/go"
+)
+
+func main() {
+	if err := run(); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+func client(path string) (*orbit.Client, string, error) {
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return nil, "", err
+	}
+	var v struct {
+		Token   string `json:"token"`
+		QueueID string `json:"queue_id"`
+	}
+	if err := json.Unmarshal(raw, &v); err != nil {
+		return nil, "", err
+	}
+	c, err := orbit.NewClient(os.Getenv("ORBIT_URL"), orbit.Options{Token: v.Token})
+	return c, v.QueueID, err
+}
+func run() (err error) {
+	a, qa, err := client(os.Getenv("ORBIT_CREDENTIALS_FILE"))
+	if err != nil {
+		return err
+	}
+	b, qb, err := client(os.Getenv("ORBIT_SECOND_CREDENTIALS_FILE"))
+	if err != nil {
+		return err
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+	defer cancel()
+	before, err := a.GetApplicationResources(ctx)
+	if err != nil {
+		return err
+	}
+	peer, err := b.GetApplicationResources(ctx)
+	if err != nil {
+		return err
+	}
+	if before.ApplicationID != peer.ApplicationID || qa == qb || before.UnfinishedTasks != 0 {
+		return errors.New("use two namespaces in the same idle, dedicated example application")
+	}
+	op, err := orbit.NewWorkerMessageID()
+	if err != nil {
+		return err
+	}
+	config, err := a.ConfigureApplicationResources(ctx, "config-"+op, orbit.ConfigureApplicationResourcesRequest{ExpectedRevision: before.Revision, Reason: "cross namespace resource example", MaxUnfinishedTasks: 1, MaxConcurrency: 2, RatePerSecond: 10})
+	if err != nil {
+		return err
+	}
+	defer func() {
+		cleanup, stop := context.WithTimeout(context.Background(), 8*time.Second)
+		defer stop()
+		_, restoreErr := a.ConfigureApplicationResources(cleanup, "restore-"+op, orbit.ConfigureApplicationResourcesRequest{ExpectedRevision: config.Resources.Revision, Reason: "restore example configuration", MaxUnfinishedTasks: before.MaxUnfinishedTasks, MaxConcurrency: before.MaxConcurrency, RatePerSecond: before.RatePerSecond})
+		err = errors.Join(err, restoreErr)
+	}()
+	input := orbit.SubmitTaskRequest{QueueID: qa, Handler: "object.prepare", HandlerVersion: "v1", PayloadVersion: "v1", Payload: json.RawMessage(`{"object_ref":"objects/example"}`), TaskTimeoutMS: 20000, Retry: orbit.RetryPolicy{MaxAttempts: 1, AttemptTimeoutMS: 10000}}
+	first, err := a.SubmitTask(ctx, "first-"+op, input)
+	if err != nil {
+		return err
+	}
+	input.QueueID = qb
+	_, err = b.SubmitTask(ctx, "second-"+op, input)
+	var full *orbit.APIError
+	if !errors.As(err, &full) || full.Code != "APPLICATION_FULL" {
+		return fmt.Errorf("expected APPLICATION_FULL, got %v", err)
+	}
+	fmt.Printf("cross_namespace_backpressure=%s http=%d\n", full.Code, full.StatusCode)
+	if _, err := a.CancelTask(ctx, first.Task.ID, "cancel-first-"+op, orbit.CancelTaskRequest{ExpectedRevision: 1, Reason: "free shared slot"}); err != nil {
+		return err
+	}
+	second, err := b.SubmitTask(ctx, "second-"+op, input)
+	if err != nil {
+		return err
+	}
+	fmt.Printf("same_identity_retry_accepted=%t\n", second.Task.State == orbit.TaskWaiting)
+	if _, err := b.CancelTask(ctx, second.Task.ID, "cancel-second-"+op, orbit.CancelTaskRequest{ExpectedRevision: 1, Reason: "complete example"}); err != nil {
+		return err
+	}
+	after, err := a.GetApplicationResources(ctx)
+	if err != nil {
+		return err
+	}
+	fmt.Printf("unfinished=%d active=%d pending_starts=%d\n", after.UnfinishedTasks, after.ActiveAttempts, after.PendingStarts)
+	return nil
+}