verifying-taubyte-functions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Verifying Taubyte Functions

验证Taubyte函数

When to use

适用场景

"Does this Go function compile to WASM?"
"Smoke-test the function before pushing"
"Check whether the deployed function actually responds"
Need to hit a
```
*.localtau
```
URL from the browser
Avoiding root-owned artifacts left behind by
```
tau build
```

"这个Go函数能否编译为WASM？"
"推送前对函数进行冒烟测试"
"检查已部署的函数是否能正常响应"
需要从浏览器访问
```
*.localtau
```
格式的URL
避免
```
tau build
```
留下root权限的产物

Two distinct things

两类不同的验证场景

Goal	Use this section
Compile WASM locally to confirm the source builds	"Local Go WASM verify (Docker)" below
Hit a function running on Dream	"Runtime verification (Dream gateway)" below

tau build

exists, but its Docker workflow tends to leave root-owned artifacts (

go.sum

lib/

main.go

) in the function tree. The Docker recipe below avoids that.

目标	参考章节
本地编译WASM以确认源码可构建	下方的「本地Go WASM验证（Docker）」
访问运行在Dream上的函数	下方的「运行时验证（Dream网关）」

tau build

工具是存在的，但它的Docker工作流会在函数目录中留下root权限的产物（如

go.sum

、

lib/

、

main.go

）。下面的Docker脚本可以避免这个问题。

Local Go WASM verify (Docker)

本地Go WASM验证（Docker）

Run from the function root (the directory containing

go.mod

and the source

.go

files):

bash

cd <project>/code/functions/<fn>

mkdir -p out

docker run --rm \
  -e CODE=/src \
  -e GOPROXY=https://proxy.golang.org,direct \
  -e GOSUMDB=sum.golang.org \
  -v "$(pwd)/out:/out" \
  --mount type=bind,src="$(pwd)",dst=/src_ro,ro \
  --mount type=tmpfs,dst=/src \
  taubyte/go-wasi:latest /bin/bash -lc '
    set -euo pipefail
    rsync -a --delete /src_ro/ /src/ 2>/dev/null || cp -a /src_ro/. /src/
    cd /src
    export CODE=/src
    # go-wasi:latest: go/tinygo live under /usr/local/* but are often missing from PATH in non-login shells (same class of env Dream uses when running build.sh).
    export PATH="/usr/local/go/bin:/usr/local/tinygo/bin:${PATH}"
    source /utils/wasm.sh
    ls -la /out
  '

Why this shape:

```
--mount type=bind,...,ro
```
makes your real source read-only inside the container.
```
--mount type=tmpfs,dst=/src
```
provides a writable scratch copy at
```
/src
```
.
The script
```
rsync
```
s the read-only source into the tmpfs, builds there, and writes only into the host-mapped
```
out/
```
directory.
Result: no root-owned files appear in your real source tree.

从函数根目录（包含

go.mod

和

.go

源码文件的目录）执行：

bash

cd <project>/code/functions/<fn>

mkdir -p out

docker run --rm \
  -e CODE=/src \
  -e GOPROXY=https://proxy.golang.org,direct \
  -e GOSUMDB=sum.golang.org \
  -v "$(pwd)/out:/out" \
  --mount type=bind,src="$(pwd)",dst=/src_ro,ro \
  --mount type=tmpfs,dst=/src \
  taubyte/go-wasi:latest /bin/bash -lc '
    set -euo pipefail
    rsync -a --delete /src_ro/ /src/ 2>/dev/null || cp -a /src_ro/. /src/
    cd /src
    export CODE=/src
    # go-wasi:latest: go/tinygo live under /usr/local/* but are often missing from PATH in non-login shells (same class of env Dream uses when running build.sh).
    export PATH="/usr/local/go/bin:/usr/local/tinygo/bin:${PATH}"
    source /utils/wasm.sh
    ls -la /out
  '

脚本设计思路：

```
--mount type=bind,...,ro
```
将本地真实源码以只读方式挂载到容器内。
```
--mount type=tmpfs,dst=/src
```
在
```
/src
```
路径提供可写的临时副本。
脚本将只读源码同步到tmpfs中，在tmpfs中执行构建，仅将产物写入宿主机映射的
```
out/
```
目录。
结果：本地源码树中不会出现root权限的文件。

Naive bind-mount (avoid)

简易绑定挂载（不推荐）

Running taubyte/go-wasi
(or similar) with $(pwd):/src
read-write and no tmpfs scratch layer can drop root-owned

lib/

main.go

, moved sources, or zips into git. Never commit that junk — use the tmpfs pattern above; git status
must be clean before tau push
(field-reported footgun).

直接以读写方式将

$(pwd):/src

挂载到

taubyte/go-wasi

容器（不使用tmpfs临时层），会在git目录中留下root权限的

lib/

、

main.go

、移动的源码或压缩包。绝对不要提交这些垃圾文件——请使用上述tmpfs方案；执行

tau push

前必须保证

git status

显示干净（这是用户反馈的常见陷阱）。

Notes

注意事项

The function's
```
.taubyte/config.yaml
```
declares the build image (e.g.
```
taubyte/go-wasi:latest
```
or
```
taubyte/go-wasi:v2
```
). Use the same image in the local recipe as the cloud will use.
Don't use
```
-it
```
in non-TTY environments — it fails with
```
cannot attach stdin to a TTY-enabled container
```
. The recipe above already omits
```
-it
```
.
The recipe is intended only when the user explicitly asks for local build verification. Default Taubyte workflow is "push to GitHub → cloud builds".
taubyte/go-wasi:latest
+
PATH
: the image installs go
and tinygo
under
```
/usr/local/go/bin
```
and
```
/usr/local/tinygo/bin
```
. Non-login shells (this Docker block, Dream/monkey running
```
.taubyte/build.sh
```
) often start with a minimal
PATH
, so
```
/utils/wasm.sh
```
can fail with go: command not found
unless you export
```
PATH
```
(shown in the recipe above) or put the same
```
export
```
at the top of .taubyte/build.sh
before
```
. /utils/wasm.sh
```
— see configuring-taubyte-build-runtime.

函数的
```
.taubyte/config.yaml
```
文件声明了构建镜像（如
```
taubyte/go-wasi:latest
```
或
```
taubyte/go-wasi:v2
```
）。本地脚本使用的镜像必须与云端使用的一致。
在非TTY环境中不要使用
```
-it
```
参数——会报错
```
cannot attach stdin to a TTY-enabled container
```
。上述脚本已省略
```
-it
```
。
该脚本仅适用于用户明确需要本地构建验证的场景。Taubyte的默认工作流是「推送到GitHub → 云端构建」。
taubyte/go-wasi:latest
+
PATH
：该镜像将
```
go
```
和
```
tinygo
```
安装在
```
/usr/local/go/bin
```
和
```
/usr/local/tinygo/bin
```
路径下。非登录shell（如本Docker块、Dream/monkey运行
```
.taubyte/build.sh
```
时）通常使用最小化
PATH
，因此如果不导出
```
PATH
```
（如上述脚本所示）或在
```
.taubyte/build.sh
```
顶部添加同样的
```
export
```
命令再执行
```
. /utils/wasm.sh
```
，
```
/utils/wasm.sh
```
可能会报错**
```
go: command not found
```
**——详情请参考configuring-taubyte-build-runtime。

Output expectation

预期输出

After the run,

out/

on the host should contain at least the WASM artifact and any expected build outputs. If

out/

is empty, the build failed; re-read the container's stdout for compile errors.

执行完成后，宿主机的

out/

目录应至少包含WASM产物和其他预期构建输出。如果

out/

为空，说明构建失败；请重新查看容器的标准输出以排查编译错误。

Runtime verification (Dream gateway)

运行时验证（Dream网关）

To curl a function running on Dream, you need (1) the gateway port and (2) the function's domain FQDN.

bash

undefined

要curl访问运行在Dream上的函数，你需要（1）网关端口和（2）函数的域名FQDN。

bash

undefined

1. Discover gateway port

1. 发现网关端口

dream status gateway

often prints a blank line before

@ http://...

; awk '/@ http/{print $3}' can return empty — prefer:

dream status gateway

常在

@ http://...

前输出空行；使用awk '/@ http/{print $3}'可能返回空值——推荐使用：

GW=$(dream status gateway default | grep -Eo 'http://[0-9.]+:[0-9]+' | head -n1)

2. Read the function's FQDN from its domain YAML

2. 从域名YAML文件中读取函数的FQDN

FQDN=$(awk '/^fqdn:/{print $2; exit}' config/domains/<domain>.yaml)

3. Curl with Host header

3. 携带Host头执行curl请求

curl -i -H "Host: $FQDN" "$GW/<path>"


Concrete example for a `ping_pong`-templated function on `/ping`:

```bash
curl -i -H "Host: <random>.default.localtau" "http://127.0.0.1:<gateway_port>/ping"

curl -i -H "Host: $FQDN" "$GW/<path>"


针对`ping_pong`模板函数访问`/ping`路径的具体示例：

```bash
curl -i -H "Host: <random>.default.localtau" "http://127.0.0.1:<gateway_port>/ping"

Expected: HTTP 200 and body "PONG"

预期结果：HTTP 200状态码，响应体为"PONG"

undefined

undefined

Hosts file for

*.localtau

(browser convenience)

*.localtau

的Hosts文件配置（浏览器便捷访问）

Browsers don't let you set a

Host:

header trivially. To hit

http://<fqdn>/<path>

directly, map the generated FQDN to localhost:

bash

sudo sh -c 'echo "127.0.0.1 <random>.default.localtau" >> /etc/hosts'

浏览器无法轻松设置

Host:

头。要直接访问

http://<fqdn>/<path>

，需将生成的FQDN映射到localhost：

bash

sudo sh -c 'echo "127.0.0.1 <random>.default.localtau" >> /etc/hosts'

or edit /etc/hosts manually:

或手动编辑/etc/hosts文件：

127.0.0.1 <random>.default.localtau


After the mapping, browsing to `http://<random>.default.localtau:<gateway_port>/<path>` works directly.

Re-run for each new generated FQDN you want to open in a browser. To find the FQDN:

```bash
awk '/^fqdn:/{print $2; exit}' config/domains/<domain>.yaml


完成映射后，即可直接在浏览器中访问`http://<random>.default.localtau:<gateway_port>/<path>`。

如需在浏览器中打开新生成的FQDN，请重复上述操作。查找FQDN的命令：

```bash
awk '/^fqdn:/{print $2; exit}' config/domains/<domain>.yaml

Workflow checklists

工作流检查清单

Pre-push local smoke

推送前本地冒烟测试

Smoke check progress:
- [ ] cd into function root (has go.mod)
- [ ] Run Docker WASM build recipe (above)
- [ ] Confirm out/ contains expected artifacts
- [ ] Inspect container stdout for errors
- [ ] If green, proceed to push

冒烟测试进度：
- [ ] 进入函数根目录（包含go.mod）
- [ ] 执行Docker WASM构建脚本（上述内容）
- [ ] 确认out/目录包含预期产物
- [ ] 检查容器标准输出是否有错误
- [ ] 若一切正常，继续执行推送

Post-deploy runtime check

部署后运行时检查

Runtime check progress:
- [ ] dream status gateway <universe> -> note port (use grep -Eo 'http://[0-9.]+:[0-9]+' if awk returns empty)
- [ ] Read FQDN from config/domains/<domain>.yaml
- [ ] curl -i -H "Host: <fqdn>" http://127.0.0.1:<port>/<path>
- [ ] Expect HTTP 200 + expected body
- [ ] If non-200, see diagnosing-dream-builds for build/log inspection

运行时检查进度：
- [ ] 执行dream status gateway <universe> -> 记录端口（若awk返回空值，使用grep -Eo 'http://[0-9.]+:[0-9]+'命令）
- [ ] 从config/domains/<domain>.yaml中读取FQDN
- [ ] 执行curl -i -H "Host: <fqdn>" http://127.0.0.1:<port>/<path>
- [ ] 预期结果：HTTP 200状态码 + 预期响应体
- [ ] 若状态码非200，请参考diagnosing-dream-builds技能检查构建/日志

Gotchas

注意事项

Don't run
tau build
casually. It works, but it can leave root-owned artifacts (
```
lib/
```
,
```
main.go
```
,
```
artifact.zip
```
) in the function tree. Never commit those — they break Dream/go-wasi builds (mixed packages, import cycles). Prefer the Docker recipe above; delete +
```
git rm --cached
```
if they appear, and add
```
.gitignore
```
patterns for them.
Wrong
Host:
header = 404. Dream's gateway routes by
```
Host:
```
; without the right header you'll see
```
404
```
even with a healthy function. Re-read the FQDN from the domain YAML.
Some gateways require
Host
to include the port. If you see
```
no substrate match found
```
while the gateway is reachable, retry with
```
-H "Host: <fqdn>:<gateway_port>"
```
.
Stale gateway port across sessions.
```
dream status gateway
```
is the canonical source; ports change between Dream runs.
Generated FQDNs only resolve via hosts mapping. They aren't real DNS; the browser must be told
```
127.0.0.1
```
.
Remote vs Dream: this skill is Dream-focused. For remote clouds, hit the FQDN directly over the public DNS the cloud configured.

不要随意运行
tau build
。它虽然能工作，但会在函数目录中留下root权限的产物（如
```
lib/
```
、
```
main.go
```
、
```
artifact.zip
```
）。绝对不要提交这些文件——它们会破坏Dream/go-wasi的构建（如包冲突、导入循环）。优先使用上述Docker脚本；若已出现此类文件，请删除并执行
```
git rm --cached
```
，同时在
```
.gitignore
```
中添加对应的忽略规则。
错误的
Host:
头会导致404。Dream网关通过
```
Host:
```
头路由请求；即使函数正常运行，若无正确的头信息也会返回
```
404
```
。请重新从域名YAML文件中确认FQDN。
部分网关要求
Host
头包含端口。若网关可访问但返回
```
no substrate match found
```
，请尝试使用
```
-H "Host: <fqdn>:<gateway_port>"
```
重新请求。
会话间网关端口可能变化。
```
dream status gateway
```
是获取端口的权威方式；Dream重启后端口可能改变。
生成的FQDN仅能通过Hosts映射解析。它们不是真实的DNS域名；必须告知浏览器将其指向
```
127.0.0.1
```
。
远程云与Dream的区别：本技能针对Dream环境。对于远程云平台，可直接通过云配置的公共DNS访问FQDN。

verifying-taubyte-functions

Original

Translation

Verifying Taubyte Functions

验证Taubyte函数

When to use

适用场景

Two distinct things

两类不同的验证场景

Local Go WASM verify (Docker)

本地Go WASM验证（Docker）

Naive bind-mount (avoid)

简易绑定挂载（不推荐）

Notes

注意事项

Output expectation

预期输出

Runtime verification (Dream gateway)

运行时验证（Dream网关）

1. Discover gateway port

1. 发现网关端口

dream status gateway often prints a blank line before @ http://...; awk '/@ http/{print $3}' can return empty — prefer:

dream status gateway常在@ http://...前输出空行；使用awk '/@ http/{print $3}'可能返回空值——推荐使用：

2. Read the function's FQDN from its domain YAML

2. 从域名YAML文件中读取函数的FQDN

3. Curl with Host header

3. 携带Host头执行curl请求

Expected: HTTP 200 and body "PONG"

预期结果：HTTP 200状态码，响应体为"PONG"

Hosts file for *.localtau (browser convenience)

*.localtau的Hosts文件配置（浏览器便捷访问）

or edit /etc/hosts manually:

或手动编辑/etc/hosts文件：

127.0.0.1 <random>.default.localtau

127.0.0.1 <random>.default.localtau

Workflow checklists

工作流检查清单

Pre-push local smoke

推送前本地冒烟测试

Post-deploy runtime check

部署后运行时检查

Gotchas

注意事项

Related skills

相关技能

`dream status gateway`
often prints a blank line before
`@ http://...`
; awk '/@ http/{print $3}' can return empty — prefer:

`dream status gateway`
常在
`@ http://...`
前输出空行；使用awk '/@ http/{print $3}'可能返回空值——推荐使用：

Hosts file for
`*.localtau`
(browser convenience)

`*.localtau`
的Hosts文件配置（浏览器便捷访问）