Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -17,5 +17,7 @@

# frontend
web/node_modules/
web/.generated/
web/dist/
internal/webui/dist/*
!internal/webui/dist/.gitkeep
2 changes: 1 addition & 1 deletion Makefile
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
.PHONY: web build

# Build the frontend into internal/webui/dist (requires Node 20+).
# Build into web/dist and copy packed assets into internal/webui/dist (requires Node 20+).
# The postbuild npm script restores dist/.gitkeep so plain `go build`
# keeps working on clean checkouts.
web:
Expand Down
7 changes: 4 additions & 3 deletions docs/WEBUI.md
Original file line number Diff line number Diff line change
Expand Up @@ -507,7 +507,8 @@ web/

`vite.config.ts`:

- `build.outDir = '../internal/webui/dist'`,`build.emptyOutDir = true`。
- `build.outDir = 'dist'`,`build.emptyOutDir = true`。`web/dist` 保留原始资源供 Vite preview 使用;构建插件将资源复制到 `internal/webui/dist`,其中 HTML、JS、CSS 等文本按 gzip 压缩存储,字体保持 WOFF2。Go 的 `assetFS` 每个资源仅解压一次,每次打开提供独立读取位置,保留 MIME、HEAD、Range 和缓存行为。
- 发布构建自动从前端源码和 Go 后端消息收集固定字符,裁剪 Noto Sans SC 字形,保留可变字重、hinting 和排版特性。Geist 与 Geist Mono 保留完整字库;动态内容中未内置的字形使用现有系统字体回退。开发模式保留完整 Noto Sans SC 字库,新增文案不需要手动维护字符清单。开发与发布构建分别使用 `web/.generated/fonts-dev` 和 `web/.generated/fonts`,避免互相覆盖。
- dev 代理必须兼容 §8 的 Host/Origin 校验(字符串简写会保留 5173 的 Host 与 Origin,导致全部请求 403):

```ts
Expand Down Expand Up @@ -536,7 +537,7 @@ build: web
go build -o geektrust ./cmd/geektrust
```

`.gitkeep` 保全(关键):Vite `emptyOutDir=true` 会删除被跟踪的 `dist/.gitkeep`;只靠 Makefile 的 touch 步骤无法约束直接执行 `npm run build` 的门槛,删除一旦被提交,干净检出的 `go build` 会因 embed 无匹配文件而失败。因此由 `web/package.json` 的 `postbuild` 脚本负责重建(npm 在 build 后自动执行,跨平台 Node 实现,不依赖 shell):
`.gitkeep` 保全:嵌入资源复制步骤保留既有的 `internal/webui/dist/.gitkeep`,缺失时创建,保证干净检出的 `go build` 有匹配的 embed 文件;`web/package.json` 的 `postbuild` 脚本也保留该文件(npm 在 build 后自动执行,跨平台 Node 实现,不依赖 shell):

```json
"scripts": {
Expand All @@ -547,7 +548,7 @@ build: web

前端开发:`go run ./cmd/geektrust run`(终端 1)+ `npm --prefix web run dev`(终端 2,Vite 5173 端口)。不做进程编排。

`internal/webui/dist` embed 规则:`//go:embed all:dist`(`all:` 前缀包含 `.gitkeep` 点文件,已核实可编译);git 中只跟踪 `dist/.gitkeep`。`Server` 启动时检测 `index.html` 缺失则页面路由返回占位页(200,说明"前端未构建,运行 make web"),API 不受影响。`.gitignore` 增加 `web/node_modules/` 与 `internal/webui/dist/*`(`!internal/webui/dist/.gitkeep`)。
`internal/webui/dist` embed 规则:`//go:embed all:dist`(`all:` 前缀包含 `.gitkeep` 点文件,已核实可编译);git 中只跟踪 `dist/.gitkeep`。`Server` 启动时检测 `index.html` 和 `index.html.gz` 均缺失则页面路由返回占位页(200,说明"前端未构建,运行 make web"),API 不受影响。`.gitignore` 增加 `web/node_modules/`、`web/.generated/`、`web/dist/` 与 `internal/webui/dist/*`(`!internal/webui/dist/.gitkeep`)。

### 9.3 页面布局

Expand Down
94 changes: 94 additions & 0 deletions internal/webui/assets.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
package webui

import (
"bytes"
"compress/gzip"
"errors"
"io"
"io/fs"
"strings"
"sync"
)

// assetFS presents gzip-stored build assets as their original files. The
// HTTP file server keeps its existing MIME types, HEAD and Range behavior.
// Plain assets and the clean-checkout placeholder work through the same FS.
type assetFS struct {
fs.FS
mu sync.Mutex
loaded map[string]func() (*assetContent, error)
}

func (f *assetFS) Open(name string) (fs.File, error) {
file, err := f.FS.Open(name)
if !errors.Is(err, fs.ErrNotExist) || !fs.ValidPath(name) {
return file, err
}
// Embedded assets are immutable. Decode each existing gzip file once;
// Stat, HEAD and subsequent requests still get independent file cursors.
f.mu.Lock()
load := f.loaded[name]
if load == nil {
packed, packedErr := f.FS.Open(name + ".gz")
if packedErr != nil {
f.mu.Unlock()
return nil, err
}
load = sync.OnceValues(func() (*assetContent, error) { return readAsset(packed) })
if f.loaded == nil {
f.loaded = make(map[string]func() (*assetContent, error))
}
f.loaded[name] = load
}
f.mu.Unlock()
content, err := load()
if err != nil {
return nil, err
}
return &assetFile{Reader: bytes.NewReader(content.data), info: content.info}, nil
}

type assetContent struct {
data []byte
info assetInfo
}

func readAsset(packed fs.File) (*assetContent, error) {
defer packed.Close()
info, err := packed.Stat()
if err != nil {
return nil, err
}
reader, err := gzip.NewReader(packed)
if err != nil {
return nil, err
}
data, readErr := io.ReadAll(reader)
closeErr := reader.Close()
if readErr != nil {
return nil, readErr
}
if closeErr != nil {
return nil, closeErr
}
return &assetContent{
data: data,
info: assetInfo{FileInfo: info, size: int64(len(data))},
}, nil
}

type assetFile struct {
*bytes.Reader
info assetInfo
}

func (f *assetFile) Stat() (fs.FileInfo, error) { return f.info, nil }
func (f *assetFile) Close() error { return nil }

type assetInfo struct {
fs.FileInfo
size int64
}

func (i assetInfo) Name() string { return strings.TrimSuffix(i.FileInfo.Name(), ".gz") }
func (i assetInfo) Size() int64 { return i.size }
145 changes: 145 additions & 0 deletions internal/webui/assets_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,145 @@
package webui

import (
"bytes"
"compress/gzip"
"errors"
"fmt"
"io"
"io/fs"
"mime"
"net/http/httptest"
"strings"
"sync"
"sync/atomic"
"testing"
"testing/fstest"
"time"
)

func gzipAsset(t *testing.T, data []byte) []byte {
t.Helper()
var packed bytes.Buffer
writer := gzip.NewWriter(&packed)
if _, err := writer.Write(data); err != nil {
t.Fatal(err)
}
if err := writer.Close(); err != nil {
t.Fatal(err)
}
return packed.Bytes()
}

func TestCompressedAssetsPreserveHTTPBehavior(t *testing.T) {
html := "<!doctype html><div id=\"root\"></div>"
script := "console.log('the original JavaScript');"
// Go uses the host MIME database, including the Windows registry.
javascriptType := mime.TypeByExtension(".js")
font := []byte("wOF2 unchanged font")
modified := time.Date(2025, 1, 2, 3, 4, 5, 0, time.UTC)
files := fstest.MapFS{
"index.html.gz": {Data: gzipAsset(t, []byte(html)), ModTime: modified},
"assets/panel.js.gz": {Data: gzipAsset(t, []byte(script)), ModTime: modified},
"assets/panel.woff2": {Data: font, ModTime: modified},
}
server := &Server{dist: &assetFS{FS: files}, hasUI: true}
for _, tc := range []struct {
name, method, path, header, value, body, contentType, cache string
status int
}{
{"index", "GET", "/", "", "", html, "text/html", "no-cache", 200},
{"script", "GET", "/assets/panel.js", "", "", script, javascriptType, "public, max-age=31536000, immutable", 200},
{"head", "HEAD", "/assets/panel.js", "", "", "", javascriptType, "public, max-age=31536000, immutable", 200},
{"range", "GET", "/assets/panel.js", "Range", "bytes=7-12", script[7:13], javascriptType, "public, max-age=31536000, immutable", 206},
{"not modified", "GET", "/assets/panel.js", "If-Modified-Since", modified.Format("Mon, 02 Jan 2006 15:04:05 GMT"), "", "", "public, max-age=31536000, immutable", 304},
{"spa fallback", "GET", "/some/route", "", "", html, "text/html", "no-cache", 200},
{"font", "GET", "/assets/panel.woff2", "", "", string(font), "", "public, max-age=31536000, immutable", 200},
} {
t.Run(tc.name, func(t *testing.T) {
request := httptest.NewRequest(tc.method, tc.path, nil)
if tc.header != "" {
request.Header.Set(tc.header, tc.value)
}
response := httptest.NewRecorder()
server.handleStatic(response, request)
if response.Code != tc.status || response.Body.String() != tc.body {
t.Fatalf("response = %d %q, want %d %q", response.Code, response.Body.String(), tc.status, tc.body)
}
if !strings.HasPrefix(response.Header().Get("Content-Type"), tc.contentType) {
t.Errorf("Content-Type = %q", response.Header().Get("Content-Type"))
}
if response.Header().Get("Cache-Control") != tc.cache || response.Header().Get("Content-Encoding") != "" {
t.Errorf("unexpected cache or encoding headers: %v", response.Header())
}
if tc.method == "HEAD" && response.Header().Get("Content-Length") != fmt.Sprint(len(script)) {
t.Errorf("HEAD length = %q, want %d", response.Header().Get("Content-Length"), len(script))
}
if tc.name == "range" && response.Header().Get("Content-Range") != fmt.Sprintf("bytes 7-12/%d", len(script)) {
t.Errorf("Content-Range = %q", response.Header().Get("Content-Range"))
}
})
}
response := httptest.NewRecorder()
server.handleStatic(response, httptest.NewRequest("GET", "/assets/missing.js", nil))
if response.Code != 404 {
t.Fatalf("missing asset = %d", response.Code)
}
}

func TestCompressedAssetCorruptionIsRejected(t *testing.T) {
packed := gzipAsset(t, []byte("original bytes"))
packed[len(packed)-8] ^= 1 // invalidate the CRC without damaging the header
files := &assetFS{FS: fstest.MapFS{"index.html.gz": {Data: packed}}}
if _, err := files.Open("index.html"); err == nil {
t.Fatal("accepted a corrupt compressed asset")
}
if _, err := files.Open("../index.html"); err == nil {
t.Fatal("accepted a path outside the embedded filesystem")
}
if _, err := files.Open("missing.js"); !errors.Is(err, fs.ErrNotExist) {
t.Fatalf("missing file: %v", err)
}
}

type countedAssets struct {
fs.FS
packedOpens atomic.Int32
}

func (f *countedAssets) Open(name string) (fs.File, error) {
if strings.HasSuffix(name, ".gz") {
f.packedOpens.Add(1)
}
return f.FS.Open(name)
}

func TestCompressedAssetLoadsOnceWithIndependentConcurrentReaders(t *testing.T) {
data := strings.Repeat("immutable web asset\n", 100)
base := &countedAssets{FS: fstest.MapFS{"panel.js.gz": {Data: gzipAsset(t, []byte(data))}}}
files := &assetFS{FS: base}
var group sync.WaitGroup
start := make(chan struct{})
for range 20 {
group.Go(func() {
<-start
file, err := files.Open("panel.js")
if err != nil {
t.Error(err)
return
}
defer file.Close()
got, err := io.ReadAll(file)
if err != nil || string(got) != data {
t.Errorf("read = %q, %v", got, err)
}
})
}
close(start)
group.Wait()
if info, err := fs.Stat(files, "panel.js"); err != nil || info.Size() != int64(len(data)) {
t.Fatalf("Stat = %v, %v", info, err)
}
if got := base.packedOpens.Load(); got != 1 {
t.Fatalf("gzip file opened %d times, want 1", got)
}
}
4 changes: 2 additions & 2 deletions internal/webui/server.go
Original file line number Diff line number Diff line change
Expand Up @@ -63,8 +63,8 @@ func NewServer(hub *Hub, broker *Broker, provider ProviderAPI, cfg *config.Confi
ctx, cancel := context.WithCancel(context.Background())
s := &Server{hub: hub, broker: broker, provider: provider, cfg: cfg, lifetime: ctx, cancel: cancel}
if sub, err := fs.Sub(distFS, "dist"); err == nil {
s.dist = sub
if f, err := sub.Open("index.html"); err == nil {
s.dist = &assetFS{FS: sub}
if f, err := s.dist.Open("index.html"); err == nil {
f.Close()
s.hasUI = true
}
Expand Down
2 changes: 1 addition & 1 deletion scripts/package-release-uv.sh
Original file line number Diff line number Diff line change
Expand Up @@ -130,7 +130,7 @@ for target in "${targets[@]}"; do
if [[ "$goos" == windows ]]; then
go run ./tools/zipdir "$package_dir" "$output_dir/$package_name.zip"
else
tar -C "$work_dir" -czf "$output_dir/$package_name.tar.gz" "$package_name"
tar -C "$work_dir" -cf - "$package_name" | gzip -9 > "$output_dir/$package_name.tar.gz"
fi
done

Expand Down
2 changes: 1 addition & 1 deletion scripts/package-release.sh
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ for target in "${targets[@]}"; do
if [[ "$goos" == windows ]]; then
go run ./tools/zipdir "$package_dir" "$archive"
else
tar -C "$package_tmp" -czf "$archive" "$package_name"
tar -C "$package_tmp" -cf - "$package_name" | gzip -9 > "$archive"
fi
done

Expand Down
4 changes: 4 additions & 0 deletions tools/zipdir/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ package main

import (
"archive/zip"
"compress/flate"
"fmt"
"io"
"io/fs"
Expand Down Expand Up @@ -54,6 +55,9 @@ func zipDir(source, output string) (err error) {
}()

archive := zip.NewWriter(out)
archive.RegisterCompressor(zip.Deflate, func(writer io.Writer) (io.WriteCloser, error) {
return flate.NewWriter(writer, flate.BestCompression)
})
defer func() {
if closeErr := archive.Close(); err == nil {
err = closeErr
Expand Down
50 changes: 50 additions & 0 deletions web/build/embed.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
// @vitest-environment node

import { mkdtemp, mkdir, writeFile, readFile, readdir, realpath, rm } from "node:fs/promises";
import { existsSync } from "node:fs";
import os from "node:os";
import path from "node:path";
import { gzipSync, gunzipSync } from "node:zlib";
import { build } from "vite";
import { expect, test } from "vitest";
import { embeddedAssets } from "./embed";

test("packed assets restore Vite output and preserve the checkout marker and existing gzip sidecars", async () => {
const directory = await realpath(await mkdtemp(path.join(os.tmpdir(), "panel-packed-assets-")));
const root = path.join(directory, "web");
const destination = path.join(directory, "internal/webui/dist");
try {
await mkdir(path.join(root, "public"), { recursive: true });
await mkdir(destination, { recursive: true });
await writeFile(path.join(destination, ".gitkeep"), "checkout marker");
await writeFile(path.join(destination, "stale.js"), "old build");
await writeFile(path.join(root, "index.html"), '<script type="module" src="/main.js"></script>');
await writeFile(path.join(root, "main.js"), `document.body.textContent = ${JSON.stringify("compressible text ".repeat(100))};`);
const json = JSON.stringify({ message: "current content ".repeat(100) });
const sidecar = gzipSync(Buffer.from("previous gzip sidecar"));
await writeFile(path.join(root, "public/data.json"), json);
await writeFile(path.join(root, "public/data.json.gz"), sidecar);
await build({ root, configFile: false, logLevel: "silent", plugins: [embeddedAssets()] });
expect(await readFile(path.join(destination, ".gitkeep"), "utf8")).toBe("checkout marker");
expect(existsSync(path.join(destination, "stale.js"))).toBe(false);
expect(await readFile(path.join(destination, "data.json"), "utf8")).toBe(json);
expect(await readFile(path.join(destination, "data.json.gz"))).toEqual(sidecar);
let files = 0;
async function compare(relative: string): Promise<void> {
for (const entry of await readdir(path.join(root, "dist", relative), { withFileTypes: true })) {
const name = path.join(relative, entry.name);
if (entry.isDirectory()) await compare(name);
else {
const target = path.join(destination, name);
const restored = existsSync(target) ? await readFile(target) : gunzipSync(await readFile(`${target}.gz`));
expect(restored).toEqual(await readFile(path.join(root, "dist", name)));
files++;
}
}
}
await compare("");
expect(files).toBeGreaterThan(2);
} finally {
await rm(directory, { recursive: true, force: true });
}
}, 15000);
Loading
Loading