README
¶
http/static
http/static provides project-relative static directories and SPA handlers. Import path: github.com/Ithildur/EiluneKit/http/static; package name: static.
Quick Start
spa, err := static.SPAHandler("dist", static.Options{
AppDir: appdir.Options{EnvVar: "APP_HOME"},
})
if err != nil {
return err
}
handler, err := routes.NewHandler(api.RoutesAt("/api"), routes.HandlerOptions{
NotFound: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.URL.Path == "/api" || strings.HasPrefix(r.URL.Path, "/api/") {
response.WriteJSONError(w, http.StatusNotFound, "not_found", "resource not found")
return
}
spa.ServeHTTP(w, r)
}),
})
if err != nil {
return err
}
Here api is the application's Blueprint. Pass handler to http.Server.Handler. The application selects /api and /api/… for JSON 404 responses and delegates other paths to the SPA. History fallback applies only to missing paths; other filesystem errors receive the file server's error response.
Use fallback injection when sharing a router with API endpoints. A global /* participates in method matching and conflicts with descendant routes; it can consume requests that should reach API 404/405 handlers.
For existing chi integration, explicit mounting remains available at a prefix owned exclusively by the static handler:
if _, err := static.MountSPA(r, "/app", "dist", static.Options{
Development: true,
}); err != nil {
return err
}
Resolution Rules
relPathmust be a clean project-relative path such asdistorweb/dist- absolute paths,
.and.., duplicate separators, and dirty paths are rejected withErrInvalidProjectPath - SPA resolution requires
index.html - when
Options.Developmentisfalse, discovery uses app-home env/executable sources only - when
Options.Developmentistrue, discovery also allows the working directory
Options
AppDir: passed through toappdir.DiscoverHomeDevelopment: enables working-directory fallback for local development
Contracts
SPAHandler,MountSPA,Mount,ResolveDir, andResolveSPADireach take oneOptionsstruct; usestatic.Options{}for defaults- when
Options.AppDir.Markersis empty, the package derives markers fromrelPath - invalid app-home env overrides fail fast with
appdir.ErrEnvInvalid; they do not fall back to the working directory
Documentation
¶
Overview ¶
Package static provides static file and SPA helpers. Package static 提供静态文件与 SPA 辅助函数。
Index ¶
- Variables
- func Mount(router chi.Router, prefix string, relPath string, opts Options) error
- func MountSPA(router chi.Router, prefix string, relPath string, opts Options) (http.Handler, error)
- func ResolveDir(relPath string, opts Options) (string, error)
- func ResolveSPADir(relPath string, opts Options) (string, error)
- func SPAHandler(relPath string, opts Options) (http.Handler, error)
- type Options
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidProjectPath = errors.New("static: invalid project path")
Functions ¶
func Mount ¶
Mount mounts a file server at prefix. Call Mount(router, prefix, relPath, opts). Mount 在 prefix 挂载文件服务器。 调用 Mount(router, prefix, relPath, opts)。
func MountSPA ¶
MountSPA mounts a SPA handler at prefix. Call MountSPA(router, prefix, relPath, opts). MountSPA 在 prefix 挂载 SPA handler。 调用 MountSPA(router, prefix, relPath, opts)。
func ResolveDir ¶
ResolveDir returns the directory for relPath. relPath must be project-relative. ResolveDir 返回 relPath 对应目录。 relPath 必须是项目相对路径。
func ResolveSPADir ¶
ResolveSPADir returns the SPA directory for relPath. index.html must exist. ResolveSPADir 返回 relPath 对应的 SPA 目录。 必须存在 index.html。
func SPAHandler ¶
SPAHandler returns a handler with SPA history fallback. relPath must be project-relative, for example "dist" or "web/dist". Call handler, err := SPAHandler(relPath, opts). Inject through routes.HandlerOptions.NotFound for application fallback. SPAHandler 返回带 SPA history 回退的 handler。 relPath 必须是项目相对路径，例如 "dist" 或 "web/dist"。 调用 handler, err := SPAHandler(relPath, opts)。 通过 routes.HandlerOptions.NotFound 注入应用兜底。
Source Files