@leaflow/sdk 0.5.1 → 0.6.0

package/openapi/tunnel.yaml

@@ -0,0 +1,773 @@
+components:
+  schemas:
+    ActOnTunnelRequestBody:
+      additionalProperties: false
+      properties:
+        action:
+          enum:
+            - enable
+            - disable
+          type: string
+      required:
+        - action
+      type: object
+    ChangeTunnelPlanRequestBody:
+      additionalProperties: false
+      properties:
+        plan_id:
+          format: uuid
+          type: string
+      required:
+        - plan_id
+      type: object
+    Error:
+      additionalProperties: false
+      properties:
+        code:
+          type: string
+        message:
+          type: string
+        meta:
+          additionalProperties: {}
+          type: object
+        status:
+          format: int64
+          type: integer
+      required:
+        - status
+        - message
+      type: object
+    LengthAwarePageOperationLogResource:
+      additionalProperties: false
+      properties:
+        items:
+          description: 这一页的内容
+          items:
+            $ref: "#/components/schemas/OperationLogResource"
+          type: array
+        limit:
+          description: 这一页最多几条，回显请求里的值
+          format: int64
+          type: integer
+        offset:
+          description: 跳过了多少条，回显请求里的值
+          format: int64
+          type: integer
+        total:
+          description: 命中的总条数，不只是这一页
+          format: int64
+          type: integer
+      required:
+        - items
+        - total
+        - limit
+        - offset
+      type: object
+    OpenTunnelRequestBody:
+      additionalProperties: false
+      properties:
+        display_name:
+          description: 这条隧道的名字，只影响显示
+          maxLength: 128
+          type: string
+        email:
+          description: 转发给上游面板的联系邮箱，可留空
+          format: email
+          maxLength: 255
+          type: string
+        plan_id:
+          description: 套餐 id，取自 GET /plans
+          format: uuid
+          type: string
+      required:
+        - plan_id
+        - display_name
+      type: object
+    OperationLogResource:
+      additionalProperties: false
+      properties:
+        action:
+          type: string
+        actor:
+          description: 操作者的用户 id；null 表示由平台执行
+          type:
+            - string
+            - "null"
+        created_at:
+          format: date-time
+          type: string
+        failure:
+          type: string
+        id:
+          format: uuid
+          type: string
+        payload:
+          additionalProperties: {}
+          type: object
+        subject_id:
+          type: string
+        subject_type:
+          type: string
+        succeeded:
+          type: boolean
+      required:
+        - id
+        - actor
+        - action
+        - subject_type
+        - subject_id
+        - payload
+        - succeeded
+        - failure
+        - created_at
+      type: object
+    SubscriptionResource:
+      additionalProperties: false
+      properties:
+        status:
+          description: ready 表示节点已全部下发；preparing 表示仍在下发——此时链接照样可用
+          enum:
+            - preparing
+            - ready
+          type: string
+        updated_at:
+          format: date-time
+          type: string
+        url:
+          description: 订阅地址。这是一条长期有效的凭据，等同于密码，请勿转发或截图分享
+          type: string
+        version:
+          format: int64
+          type: integer
+      required:
+        - url
+        - version
+        - status
+        - updated_at
+      type: object
+    TunnelPlanListResponseBody:
+      additionalProperties: false
+      properties:
+        items:
+          items:
+            $ref: "#/components/schemas/TunnelPlanResource"
+          type: array
+      required:
+        - items
+      type: object
+    TunnelPlanResource:
+      additionalProperties: false
+      properties:
+        description:
+          type: string
+        id:
+          format: uuid
+          type: string
+        name:
+          type: string
+        quota_bytes:
+          description: 套餐标称的流量额度，仅供比较。实际额度以隧道用量接口返回的 quota_bytes 为准
+          format: int64
+          type: integer
+        sort:
+          description: 货架上的排列顺序，越小越靠前
+          format: int64
+          type: integer
+      required:
+        - id
+        - name
+        - description
+        - quota_bytes
+        - sort
+      type: object
+    TunnelResource:
+      additionalProperties: false
+      properties:
+        created_at:
+          format: date-time
+          type: string
+        display_name:
+          type: string
+        email:
+          description: 转发给上游面板的联系邮箱；平台不使用它
+          type:
+            - string
+            - "null"
+        enabled:
+          description: 用户自己的开关。停用会把实例从调度器撤下，但端口保留，启用后原样回来
+          type: boolean
+        failure:
+          description: 最近一次上游拒绝的说明，仅在存在时非空
+          type:
+            - string
+            - "null"
+        id:
+          format: uuid
+          type: string
+        plan_id:
+          format: uuid
+          type: string
+        plan_name:
+          type: string
+        status:
+          description: deleting 表示已退订但上游尚未删除完成
+          enum:
+            - active
+            - deleting
+          type: string
+        subscription_status:
+          description: preparing 表示节点仍在下发；订阅链接此时照样可用
+          enum:
+            - preparing
+            - ready
+          type: string
+        subscription_version:
+          description: 每次重置订阅后递增
+          format: int64
+          type: integer
+        suspended:
+          description: 被平台停用（欠费、违规或项目停服）。为 true 时无法自行启用
+          type: boolean
+        suspended_at:
+          description: 被平台停用的时刻
+          format: date-time
+          type:
+            - string
+            - "null"
+        usage:
+          $ref: "#/components/schemas/TunnelUsageSnapshot"
+      required:
+        - id
+        - display_name
+        - plan_id
+        - plan_name
+        - email
+        - enabled
+        - suspended
+        - suspended_at
+        - status
+        - subscription_status
+        - subscription_version
+        - usage
+        - failure
+        - created_at
+      type: object
+    TunnelUsageSnapshot:
+      additionalProperties: false
+      properties:
+        billed_bytes:
+          description: 按线路倍率折算后的用量，配额比对以此为准
+          format: int64
+          type: integer
+        over_quota:
+          description: billed_bytes 是否已超过 quota_bytes；配额为 0 时恒为 false
+          type: boolean
+        quota_bytes:
+          description: 上游给出的真实配额，0 表示不限量
+          format: int64
+          type: integer
+        raw_bytes:
+          description: 实际传输的字节，不用于配额比对
+          format: int64
+          type: integer
+        synced_at:
+          description: 这份用量是什么时候采集的；null 表示尚未采集
+          format: date-time
+          type:
+            - string
+            - "null"
+        upload_bytes:
+          format: int64
+          type: integer
+      required:
+        - quota_bytes
+        - billed_bytes
+        - raw_bytes
+        - upload_bytes
+        - over_quota
+        - synced_at
+      type: object
+    UpdateTunnelProfileRequestBody:
+      additionalProperties: false
+      properties:
+        display_name:
+          maxLength: 128
+          type: string
+        email:
+          description: 联系邮箱。不传表示不改动，传空字符串表示清空
+          maxLength: 255
+          type:
+            - string
+            - "null"
+      required:
+        - display_name
+      type: object
+    UsageDayResource:
+      additionalProperties: false
+      properties:
+        billed_bytes:
+          format: int64
+          type: integer
+        day:
+          description: YYYY-MM-DD
+          type: string
+        raw_bytes:
+          format: int64
+          type: integer
+      required:
+        - day
+        - raw_bytes
+        - billed_bytes
+      type: object
+    UsageResource:
+      additionalProperties: false
+      properties:
+        billed_bytes:
+          description: 按线路倍率折算后的用量，配额比对以此为准
+          format: int64
+          type: integer
+        over_quota:
+          type: boolean
+        period_end:
+          description: 本期计费周期的结束日（YYYY-MM-DD）
+          type: string
+        period_start:
+          description: 本期计费周期的起始日（YYYY-MM-DD）
+          type: string
+        quota_bytes:
+          description: 上游给出的真实配额，0 表示不限量
+          format: int64
+          type: integer
+        quota_exceeded_at:
+          description: 上游判定超额的时刻；null 表示未超额
+          format: date-time
+          type:
+            - string
+            - "null"
+        raw_bytes:
+          description: 实际传输的字节，不用于配额比对
+          format: int64
+          type: integer
+        upload_bytes:
+          format: int64
+          type: integer
+        usage_percent:
+          description: 上游给出的用量百分比
+          format: double
+          type: number
+      required:
+        - quota_bytes
+        - billed_bytes
+        - raw_bytes
+        - upload_bytes
+        - usage_percent
+        - over_quota
+        - period_start
+        - period_end
+        - quota_exceeded_at
+      type: object
+    UsageSeriesResource:
+      additionalProperties: false
+      properties:
+        days:
+          description: 上游实际采用的天数，可能被它夹到 1–365
+          format: int64
+          type: integer
+        points:
+          items:
+            $ref: "#/components/schemas/UsageDayResource"
+          type: array
+      required:
+        - days
+        - points
+      type: object
+  securitySchemes:
+    bearerAuth:
+      bearerFormat: JWT
+      description: 项目令牌。先在 auth.leaflow.net 登录拿到账号令牌，再用它向 IAM 换取项目令牌（POST /api/v1/projects/{projectId}/token）——一张项目令牌同时说明当前用户和当前项目。
+      scheme: bearer
+      type: http
+info:
+  description: |-
+    Leaflow 隧道的用户接口，用于开通与管理项目的加速隧道、订阅地址和流量用量。
+
+    ## 身份与鉴权
+
+    每个请求需携带 `Authorization: Bearer <项目令牌>`。先在 auth.leaflow.net 登录获取账号令牌，再用它向 IAM 换取项目令牌（`POST /api/v1/projects/{projectId}/token`）。一张项目令牌同时说明当前用户和当前项目。
+
+    **路径和请求头上都没有 `project_id`**：当前项目由令牌决定。
+
+    鉴权在网关完成，失败的请求不会到达这些接口。按错误码区分处理方式：`TOKEN_MISSING` 表示没带令牌；`TOKEN_EXPIRED` 表示令牌过期，用账号令牌重新换取即可，无需重新登录；`TOKEN_INVALID` 表示令牌验不过；`NOT_A_MEMBER` 表示当前账号不是该项目成员；`USER_SUSPENDED` / `USER_BANNED` 表示账号本身不能操作。
+
+    ## 通用约定
+
+    - **一个项目一条隧道。** 所以路径是单数的 `/tunnel`，不带 id。已经有一条时再开通会被拒绝（`TUNNEL_ALREADY_OPEN`）。
+    - **订阅地址是凭据。** 它等同于密码，只由 `GET /tunnel/subscription` 单独返回，不出现在隧道详情或任何列表里。怀疑泄露时用重置接口，它会让已分发的每一份订阅立即失效。
+    - **停用不是退订。** 停用保留端口和订阅地址，重新启用后原样回来；退订不可逆，重新开通得到的是全新的地址。
+    - **判断超额只看 `billed_bytes`。** 线路可以设置倍率（如 1.5× 或 0×），`raw_bytes` 是实际传输量，两者不一定相等。
+    - **用量最多滞后一个采集周期。** 适合用量管控，不适合作为计费结算依据。隧道详情里那份还额外经过一层缓存，`usage.synced_at` 说明它有多旧。
+    - **换套餐不是瞬时的。** 多出来的线路马上可用，少掉的那些有宽限期，到期才真正释放。
+  title: Leaflow 隧道用户 API
+  version: 1.0.0
+openapi: 3.1.0
+paths:
+  /api/v1/operation-logs:
+    get:
+      description: |-
+        记录每一次**写**操作：谁、什么时候、做了什么、成功还是失败。读操作不记录。
+
+        `actor` 为 null 表示该操作由平台执行（例如自动重试删除、项目停服）——平台做了什么是看得到的，但具体是哪位运营人员不会展示。
+
+        `payload` 只包含路径参数与查询串，且其中像凭据的字段已被替换为占位符。
+      operationId: list-tunnel-operation-logs
+      parameters:
+        - description: 这一页最多返回多少条
+          explode: false
+          in: query
+          name: limit
+          schema:
+            default: 50
+            description: 这一页最多返回多少条
+            format: int64
+            maximum: 200
+            minimum: 1
+            type: integer
+        - description: 跳过多少条。要翻得更深请改用游标翻页的接口
+          explode: false
+          in: query
+          name: offset
+          schema:
+            description: 跳过多少条。要翻得更深请改用游标翻页的接口
+            format: int64
+            maximum: 10000
+            minimum: 0
+            type: integer
+        - description: 只看某一种操作，取值是接口的 operation id，比如 open-tunnel
+          explode: false
+          in: query
+          name: action
+          schema:
+            description: 只看某一种操作，取值是接口的 operation id，比如 open-tunnel
+            maxLength: 128
+            type: string
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/LengthAwarePageOperationLogResource"
+          description: OK
+        default:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+          description: Error
+      summary: 查看本项目的操作日志
+      tags:
+        - OperationLog
+  /api/v1/plans:
+    get:
+      description: |-
+        只返回在售的套餐，按 `sort` 升序。已下架的不在其中——但正在用它的隧道仍然正常，下架只是不再接新单。
+
+        `quota_bytes` 是套餐**标称**的额度，仅供比较；实际额度由上游按线路分组决定，以隧道用量接口返回的 `quota_bytes` 为准。
+      operationId: list-tunnel-plans
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TunnelPlanListResponseBody"
+          description: OK
+        default:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+          description: Error
+      summary: 列出可开通的套餐
+      tags:
+        - Plan
+  /api/v1/tunnel:
+    delete:
+      description: |-
+        **不可逆。** 上游账户会被删除，订阅地址立刻失效，重新开通得到的是一条全新的隧道和一条全新的订阅地址。
+
+        删除是异步的：返回时 `status` 可能仍是 `deleting`，表示上游还没删干净（通常是某台服务器暂时连不上）。平台会自动重试，期间这条隧道仍然出现在查询接口里。退订完成前无法重新开通。
+
+        只是暂时不用的话请用停用，它保留端口和订阅地址。
+      operationId: close-tunnel
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TunnelResource"
+          description: OK
+        default:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+          description: Error
+      summary: 退订隧道
+      tags:
+        - Tunnel
+    get:
+      description: |-
+        每个项目最多一条隧道。尚未开通时返回 404（`TUNNEL_NOT_FOUND`）。
+
+        响应里的 `usage` 是**缓存**的用量，`usage.synced_at` 说明它是什么时候采集的；为 null 表示尚未采集过，而不是用量为零。需要当前值请调用量接口。
+
+        **订阅地址不在这里**，它是一条长期有效的凭据，只由订阅接口单独返回。
+      operationId: get-tunnel
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TunnelResource"
+          description: OK
+        default:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+          description: Error
+      summary: 查看本项目的隧道
+      tags:
+        - Tunnel
+    patch:
+      description: |-
+        改显示名和联系邮箱，**不影响订阅、用量或线路**。
+
+        `email` 不传表示不改动，传空字符串表示清空。它会被转发给上游面板——上游拿它做什么由面板决定，平台不使用它。
+      operationId: update-tunnel-profile
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/UpdateTunnelProfileRequestBody"
+        required: true
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TunnelResource"
+          description: OK
+        default:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+          description: Error
+      summary: 修改隧道的显示信息
+      tags:
+        - Tunnel
+    post:
+      description: |-
+        为当前项目开通一条隧道，返回时订阅通常处于 `preparing`——节点仍在下发，但**订阅地址此时已经可用**，内容会在拉取那一刻按当时的状态重新派生。
+
+        一个项目只能有一条。已经有了返回 `TUNNEL_ALREADY_OPEN`；上一条还在退订中返回 `TUNNEL_CLOSING`，稍后重试即可。
+
+        套餐必须处于在售状态，已下架的返回 `TUNNEL_PLAN_RETIRED`。若返回 `TUNNEL_PLAN_GROUPS_MISSING`，说明该套餐在上游对应的线路分组不存在——这是一个配置问题，请联系运营，换一款套餐或稍后重试都不会有帮助。
+      operationId: open-tunnel
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/OpenTunnelRequestBody"
+        required: true
+      responses:
+        "201":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TunnelResource"
+          description: Created
+        default:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+          description: Error
+      summary: 开通隧道
+      tags:
+        - Tunnel
+  /api/v1/tunnel/actions:
+    post:
+      description: |-
+        **停用不是退订。** 停用会把这条隧道的实例从上游调度器撤下，但端口保留，重新启用后原样回来，订阅地址也不变。适合「这段时间不用」。
+
+        被平台停用的隧道（`suspended` 为 true）无法自行启用，会返回 `TUNNEL_SUSPENDED`——那通常是欠费或违规，需要先处理对应的问题。
+      operationId: act-on-tunnel
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ActOnTunnelRequestBody"
+        required: true
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TunnelResource"
+          description: OK
+        default:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+          description: Error
+      summary: 启用或停用隧道
+      tags:
+        - Tunnel
+  /api/v1/tunnel/plan:
+    put:
+      description: |-
+        换套餐会立刻重判线路资格：多出来的线路马上可用，**少掉的那些进入删除队列——宽限期内照常可用，到期才真正释放**。所以换套餐不是一次瞬时切换，订阅内容会在接下来一段时间内变化。
+
+        换完之后建议重新拉取一次订阅。
+      operationId: change-tunnel-plan
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ChangeTunnelPlanRequestBody"
+        required: true
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TunnelResource"
+          description: OK
+        default:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+          description: Error
+      summary: 更换套餐
+      tags:
+        - Tunnel
+  /api/v1/tunnel/subscription:
+    get:
+      description: |-
+        **返回的是一条长期有效的凭据，等同于密码。** 拿到它就能取得本项目全部节点与密码，请勿转发、截图或提交到工单。
+
+        它不会出现在隧道详情或任何列表里，只由这个接口返回。
+
+        `status` 为 `preparing` 时链接**照样可用**，内容会在拉取那一刻按当时的状态重新派生。
+
+        怀疑泄露时请调用重置接口。
+      operationId: get-tunnel-subscription
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SubscriptionResource"
+          description: OK
+        default:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+          description: Error
+      summary: 获取订阅地址
+      tags:
+        - Tunnel
+  /api/v1/tunnel/subscription/rotate:
+    post:
+      description: |-
+        **这是凭据泄露时的处置手段，会让已分发出去的每一份订阅立即失效。**
+
+        订阅 token 和节点密码同时更换，所有客户端都必须重新拉取一次订阅才能继续使用。调用前请确认这确实是想要的结果。
+
+        重置后再调订阅接口取新地址。
+      operationId: rotate-tunnel-subscription
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TunnelResource"
+          description: OK
+        default:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+          description: Error
+      summary: 重置订阅地址与节点密码
+      tags:
+        - Tunnel
+  /api/v1/tunnel/usage:
+    get:
+      description: |-
+        现场向上游查询，比隧道详情里那份缓存新。
+
+        **判断是否超额只看 `billed_bytes`**：线路可以设置倍率（如 1.5× 或 0×），`raw_bytes` 是实际传输量，两者不一定相等。`over_quota` 已经算好。
+
+        用量由上游定期采集，**最多滞后一个采集周期**，适合用量管控，不适合作为计费结算依据。
+      operationId: get-tunnel-usage
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/UsageResource"
+          description: OK
+        default:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+          description: Error
+      summary: 查看本期用量
+      tags:
+        - Tunnel
+  /api/v1/tunnel/usage/series:
+    get:
+      description: |-
+        按**自然日**切分，用于画趋势图。
+
+        **没有流量的日子不会出现在结果里**（不补零），画图前需要自行补齐日期轴，否则空档会被连成一条斜线。
+
+        **把这里的天加起来不等于本期用量**，这是有意的：本期用量按计费周期切，而且「重置本期用量」只作用于本期，日汇总一行都不删。两者回答的是不同的问题。
+      operationId: list-tunnel-usage-series
+      parameters:
+        - description: 取最近多少天，0 表示用上游的默认值（30）。上游只接受 1–365，超出会被它夹住
+          explode: false
+          in: query
+          name: days
+          schema:
+            default: 30
+            description: 取最近多少天，0 表示用上游的默认值（30）。上游只接受 1–365，超出会被它夹住
+            format: int64
+            maximum: 3650
+            minimum: 0
+            type: integer
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/UsageSeriesResource"
+          description: OK
+        default:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+          description: Error
+      summary: 查看按天用量
+      tags:
+        - Tunnel
+security:
+  - bearerAuth: []
+