[Thread] How to define blocklet interfaces

wangshijun commented 4 years ago

这是个讨论的帖子，问题来源：https://github.com/blocklet/blocklet-specification/pull/1 以及 https://github.com/ArcBlock/abt-node/issues/1252

问题描述

Blocklet 如何通过 blocklet.yml 告诉 ABT Node 对外暴露哪些服务、界面等等。典型的场景，比如：

blockchain-manager 有自己的管理界面，同时每启动一条链，还会对外暴露 gql、grpc、p2p 的端口
ip-echo-dns 有自己的管理界面，需要 routing engine 帮其暴露 53 端口，把流量转发到内部端口上
kitchen-sink 有 public/admin/config 三个界面可以对外暴露

约束条件：需要允许 blocklet 暴露任何他想要暴露的接口、服务出去。

或者换句话说，我们需要把当前 meta spec 中下列字段整合：

public_url
admin_url
doc_url
config_url
exposedService
capabilities

解决方案

在 blocklet meta 中定义 interfaces 字段，把 interface 分为 UI、API、Service 三类

interfaces:
    # define UI interfaces
    - type: UI
      name: public_url
      path: /
      port: 'BLOCKLET_PORT'
    - type: UI
      name: admin_url
      path: /admin
      port: 'BLOCKLET_PORT'

    # define API interface
    - type: API
      name: graphql
      path: /api/gql
      port: 'BLOCKLET_PORT'

    - type: API
      name: websocket
      path: /api/socket
      port: 'BLOCKLET_PORT'

    - type: API
      name: graphql
      path: /api/forge
      port: 'BLOCKLET_PORT'

    # define services
    - type: SERVICE
      protocol: udp
      name: dns
      port:
            internal: 'BLOCKLET_DNS_PORT'
            external: 53
    - type: SERVICE
      name: p2p
      port:
            internal: 'BLOCKLET_P2P_PORT'
            external: 26535

interfaces 是个列表，每个条目包含如下字段：

type: 必须，可取值为 WEB|SERVICE
name: 必须，语义化的名字，会显示在 ABT Node 里面的 Blocklet 详情页
path: 可选，当前 interface 在 blocklet 上的 url，默认值为 /
prefix: 可选，默认值为 *，可取值为，对于 type=service 的可忽略
- * 支持 serve 在任何 url 下面，安装之后可以自动生成，也可以配置
- path 能 serve 在某个特定的 path 下面，安装之后可以自动给他生成，不用也不可配置
port: 必须，为了保障简洁和灵活性，可取值为下面两种类型
- string：比如 BLOCKLET_PORT，表示需要 Node 分配一个端口号，并且用这个名字传给 Blocklet
- object：通常用于 Blocklet 对外暴露多个 Interface
  - port.internal，作用等同于字符串类型的 port，即 Blocklet 内部监听的端口
  - port.external，告诉 router 希望这个 interface 通过 router 的哪个端口对外暴露，比如 dns 的 53
protocol：可选，默认值为空，可以指定为 tcp/udp