@leaflow/sdk 0.6.0 → 0.7.0

package/openapi/tunnel.yaml

@@ -1,773 +0,0 @@
-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: []
-