指定头和路由

New with Walrus Sites Testnet version

The following features have been released with the Walrus Sites Testnet version.

在其基本配置中，Walrus Sites 通过门户提供静态资产。然而，许多现代 Web 应用程序需要更高级的功能，例如自定义标头和客户端路由。

因此，site-builder 可以读取 ws-resource.json 配置文件，您可以在其中直接指定资源标头和路由规则。

ws-resources.json 文件

此文件可选地放置在站点目录的根目录中，并且 不会 随站点的资源一起上传（换句话说，该文件不是生成的 Walrus Site 的一部分，也不会由门户提供）。

如果您不想使用此默认位置，可以在运行 publish 或 update 命令时使用 --ws-resources 标志指定配置文件的路径。

该文件是 JSON 格式的，类似如下：

{
  "headers": {
    "/index.html": {
      "Content-Type": "text/html; charset=utf-8",
      "Cache-Control": "max-age=3500"
    }
  },
  "routes": {
    "/*": "/index.html",
    "/accounts/*": "/accounts.html",
    "/path/assets/*": "/assets/asset_router.html"
  }
}

我们现在详细描述配置文件的两个部分，headers 和 routes。

指定 HTTP 响应标头

headers 部分允许您为特定资源指定自定义 HTTP 响应标头。headers 对象中的键是资源的路径，值是与门户将附加到响应的标头相对应的键值对列表。

例如，在上述配置中，文件 index.html 将以 Content-Type 标头设置为 text/html; charset=utf-8 和 Cache-Control 标头设置为 max-age=3500 提供。

此机制允许您控制资源传递的各个方面，例如缓存、编码和内容类型。

Note

The resource path is always represented as starting from the root /.

默认标头

默认情况下，无需指定标头，并且可以省略 ws-resources.json 文件。site-builder 将自动尝试根据文件扩展名推断 Content-Type 标头，并将 Content-Encoding 设置为 identity（无转换）。

如果无法推断内容类型，则 Content-Type 将设置为 application/octet-stream。

这些默认值将被 ws-resources.json 文件中指定的任何标头覆盖。

指定客户端路由

routes 部分允许您为站点指定客户端路由规则。这在您想要使用单页应用程序 (SPA) 框架（例如 React 或 Angular）时很有用。

routes 对象中的配置是从路由键到资源路径的映射。

routes 键 是 /path/to/some/* 形式的路径模式，其中 * 字符表示通配符。

Note

Currently, the wildcard can only be only be specified at the end of the path. Therefore, /path/* is a valid path, while /path/*/to and */path/to/* are not.

routes 值 是在匹配路由键时应提供的资源路径。

Important

The paths in the values must be valid resource paths, meaning that they must be present among the site's resources. The Walrus sites contract will abort if the user tries to create a route that points to a non-existing resource.

简单的路由算法如下：

  • 每当在站点资源中 找不到资源路径 时，门户会尝试将路径与 routes 匹配。
  • 然后所有匹配的路由都按 字典顺序排序，并选择 最长 的匹配。
  • 然后提供与此最长匹配相对应的资源。

Note

In other words, the portal will always serve a resource if present, and if not present will serve the resource with the longest matching prefix among the routes.

回想上面的例子：

"routes": {
  "/*": "/index.html",
  "/path/*": "/accounts.html",
  "/path/assets/*": "/assets/asset_router.html"
}

将发生以下匹配：

  • 浏览 /any/other/test.html 将提供 /index.html；
  • 浏览 /path/test.html 将提供 /accounts.html，因为它比前一个更具体；
  • 同样，浏览 /path/assets/test.html 将提供 /assets/asset_router.html。

/index.html、/accounts.html 和 /assets/asset_router.html 都是 Sui 上 Walrus Sites 对象的现有资源。