Documentation
¶
Index ¶
- Variables
- func AddSalt(rnd []byte, salt string) string
- func AutoCert(ac *autocert.Manager, tlsconf *tls.Config, handler http.Handler) http.Handler
- func ExecFunc(f any, args ...any) ([]any, error)
- func ForMethod(x any) string
- func ForType(x any, showUnexported bool, maxDepth int) string
- func GenerateRandom(length int) ([]byte, error)
- func GenerateRandomID(rnd []byte) error
- func GenerateRandomString(length int) (string, error)
- func PagePath(root, p string, index []string) (os.FileInfo, string, error)
- type Cookie
- type Cookier
- type Dot
- func (T *Dot) Close() error
- func (T *Dot) Context() context.Context
- func (T *Dot) Cookie() Cookier
- func (T *Dot) Defer(call any, args ...any) error
- func (T *Dot) Global() Globaler
- func (T *Dot) Header() http.Header
- func (T *Dot) Request() *http.Request
- func (T *Dot) RequestLimitSize(l int64) *http.Request
- func (T *Dot) Response() Responser
- func (T *Dot) RootDir(upath string) string
- func (T *Dot) SaveStatic(path string) (wr io.WriteCloser, err error)
- func (T *Dot) Session() Sessioner
- func (T *Dot) Swap() *vmap.Map
- func (T *Dot) WithContext(ctx context.Context)
- type DotContexter
- type Doter
- type DynamicTemplateFunc
- type DynamicTemplater
- type ExecCall
- type ExitCall
- type Forward
- type ForwardRewriter
- type Global
- type Globaler
- type HandleFunc
- type PluginHTTP
- type PluginHTTPClient
- type PluginRPC
- type PluginRPCClient
- type PluginType
- type Pluginer
- type Responser
- type Route
- type Router
- type ServerHandlerDynamic
- type ServerHandlerStatic
- type Session
- type Sessioner
- type Sessions
- func (T *Sessions) CheckDeadAll() []any
- func (T *Sessions) Configure(f func(*Sessions))
- func (T *Sessions) DelSession(id string)
- func (T *Sessions) GetSession(id string) (*Session, bool)
- func (T *Sessions) InstantDeadAll()
- func (T *Sessions) InstantDeadAllInto(wg *sync.WaitGroup)
- func (T *Sessions) Len() int
- func (T *Sessions) NewSession(id string) *Session
- func (T *Sessions) Session(rw http.ResponseWriter, req *http.Request) Sessioner
- func (T *Sessions) SessionID(req *http.Request) (id string, err error)
- func (T *Sessions) SetSession(id string, s *Session) *Session
- type Site
- type SiteMan
- type SitePool
Constants ¶
This section is empty.
Variables ¶
var ( SiteContextKey = &contextKey{"web-site"} // 当前站点 *Site RouterContextKey = &contextKey{"web-router"} // 路由相关对象 ListenerContextKey = &contextKey{"web-listener"} // 监听器 ConnContextKey = &contextKey{"web-conn"} // 底层连接 PluginContextKey = &contextKey{"web-plugin"} // 插件管理器 )
请求上下文中预定义的 Key,可在 Handler / 模板 / 中间件中通过 req.Context().Value(...) 取出。
示例:
if site, ok := req.Context().Value(vweb.SiteContextKey).(*vweb.Site); ok {
// 使用 site
}
Functions ¶
func AutoCert ¶
AutoCert 自动从 Let's Encrypt 申请证书
ac *autocert.Manager 申请证书管理 tlsconf *tls.Config tls配置 handler http.Handler http处理
Types ¶
type Cookie ¶
type Cookie struct {
R *http.Request // 请求
W http.ResponseWriter // 响应
}
Cookie 类型定义。
func (*Cookie) Add ¶
func (c *Cookie) Add(name, value, path, domain string, maxAge int, secure, only bool, sameSite http.SameSite)
Add 增加,写入一条Cookie,可以写入多条Cookie保存至浏览器
type Cookier ¶
type Cookier interface {
ReadAll() map[string]string // 读取所有
RemoveAll() // 删除所用
Get(name string) string // 读取
Add(name, value, path, domain string, maxAge int, secure, only bool, sameSite http.SameSite) // 增加
Del(name string) // 删除
}
Cookier 类型定义。
type Dot ¶
type Dot struct {
R *http.Request // 请求
W http.ResponseWriter // 响应
Site *Site // 网站配置
// contains filtered or unexported fields
}
Dot 模板点
func (*Dot) Defer ¶
Defer 在用户会话时间过期后,将被调用。
call any 函数 args ... any 参数或更多个函数是函数的参数 error 错误 例: .Defer(fmt.Println, "1", "2") .Defer(fmt.Printf, "%s", "汉字")
func (*Dot) SaveStatic ¶
func (T *Dot) SaveStatic(path string) (wr io.WriteCloser, err error)
SaveStatic 保存为静态文件
type DotContexter ¶
type DotContexter interface {
Context() context.Context // 上下文
WithContext(ctx context.Context) // 替换上下文
}
DotContexter 类型定义。
type Doter ¶
type Doter interface {
RootDir(path string) string // 网站的根目录
Request() *http.Request // 用户的请求信息
RequestLimitSize(l int64) *http.Request // 请求限制大小
Header() http.Header // 标头
Response() Responser // 数据写入响应
Session() Sessioner // 用户的会话缓存
Global() Globaler // 全站缓存
Cookie() Cookier // 用户的Cookie
Swap() *vmap.Map // 信息交换
Defer(call any, args ...any) error // 退回调用
SaveStatic(path string) (wr io.WriteCloser, err error) // 保存为静态文件
DotContexter // 上下文
}
Doter 可以在模本中使用的方法
type DynamicTemplateFunc ¶
type DynamicTemplateFunc func(*ServerHandlerDynamic) DynamicTemplater
DynamicTemplateFunc 声明动态模板获取函数类型
type DynamicTemplater ¶
type DynamicTemplater interface {
SetPath(root string, page string)
Parse(r io.Reader) (err error) // 解析模板内容
Execute(name string, out io.Writer, dot ...any) error // 执行模板并输出
Close() error // 释放相关资源
}
DynamicTemplater 动态模板接口规范
type ExitCall ¶
type ExitCall struct {
// contains filtered or unexported fields
}
ExitCall 任务管理
type Forward ¶
type Forward struct {
Path []string // 多种路径匹配
ExcludePath []string // 排除多种路径匹配
RePath string // 重写路径
}
Forward 原始配置结构
func (*Forward) Compile ¶
func (T *Forward) Compile() (*ForwardRewriter, error)
Compile 预编译正则,建议在程序初始化或配置加载时调用一次。 返回的 *ForwardRewriter 可被多 goroutine 并发安全地调用 Rewrite。
type ForwardRewriter ¶
type ForwardRewriter struct {
// contains filtered or unexported fields
}
ForwardRewriter 编译后的执行对象
type Globaler ¶
type Globaler interface {
Set(key, val any) // 设置
Has(key any) bool // 判断
Get(key any) any // 读取
GetHas(key any) (val any, ok bool) // 读取判断
Del(key any) // 删除
SetExpired(key any, d time.Duration) // 过期
SetExpiredCall(key any, d time.Duration, f func(any)) // 过期调用
TTL(key any) (time.Duration, bool) // 某个KEY过期时间
Range(f func(key, value any) bool) // 遍历
Reset() // 重置
}
Globaler 站点级全局键值存储接口(与 Session 类似,但作用于整个站点,非单用户)。
type HandleFunc ¶
type HandleFunc []func(Doter)
HandleFunc 类型定义。
func (HandleFunc) ServeHTTP ¶
func (T HandleFunc) ServeHTTP(w http.ResponseWriter, r *http.Request)
type PluginHTTP ¶
type PluginHTTP interface {
Type() PluginType // 类型
ServeHTTP(w http.ResponseWriter, r *http.Request) // 服务HTTP
RoundTrip(r *http.Request) (resp *http.Response, err error) // 代理
CancelRequest(req *http.Request) // 取消HTTP请求
CloseIdleConnections() // 关闭空闲连接
RegisterProtocol(scheme string, rt http.RoundTripper) // 注册新协议
}
PluginHTTP http插件接口
type PluginHTTPClient ¶
type PluginHTTPClient struct {
Tr *http.Transport // 客户端
Addr string // 地址
Scheme string // 协议(用于默认填充)
Host string // 请求Host(用于默认填充)
Dialer *net.Dialer
// contains filtered or unexported fields
}
PluginHTTPClient 插件HTTP客户端
func (*PluginHTTPClient) Connection ¶
func (T *PluginHTTPClient) Connection() (PluginHTTP, error)
Connection 快速连接HTTP
PluginHTTP 插件HTTP error 错误
type PluginRPC ¶
type PluginRPC interface {
Type() PluginType // 类型,固定返回 PluginTypeRPC
Register(value any) // 注册 struct 类型(gob)
Call(name string, arg any, reply any) error // 远程调用
Discard() error // 废弃连接(不回池)
Close() error // 关闭并回池(若支持)
}
PluginRPC rpc 插件接口。 用于与后端 RPC 服务通信:注册类型、发起调用、丢弃或关闭连接。
典型流程:
client := &PluginRPCClient{ConnPool: pool, Addr: "127.0.0.1:9000", Path: "/_goRPC_"}
rpc, err := client.Connection()
rpc.Register(MyType{})
err = rpc.Call("Service.Method", arg, &reply)
rpc.Close() // 或 Discard() 不回收连接
type PluginRPCClient ¶
type PluginRPCClient struct {
ConnPool *vconnpool.Pool // 连接池(不可为空)
Addr string // 如 "127.0.0.1:9000"
Path string // 如 "/_goRPC_"
}
PluginRPCClient 插件 RPC 客户端配置。 ConnPool 负责连接复用;Addr 为 TCP 地址;Path 为 HTTP CONNECT 路径。
func (*PluginRPCClient) Connection ¶
func (T *PluginRPCClient) Connection() (PluginRPC, error)
Connection 从连接池拨号并建立 Go net/rpc 客户端。
返回:
- PluginRPC: 可用的 RPC 句柄
- error: ConnPool 为空、拨号失败、CONNECT 握手失败等
示例:
prpc, err := client.Connection()
if err != nil { return err }
defer prpc.Close()
type PluginType ¶
type PluginType int
PluginType 插件类型枚举(具体定义可能在其它文件,此处仅作类型别名用途说明)。 常见取值:PluginTypeRPC、PluginTypeHTTP 等。
const ( PluginTypeRPC PluginType = iota PluginTypeHTTP )
type Pluginer ¶
type Pluginer interface {
RPC(name string) (PluginRPC, error)
HTTP(name string) (PluginHTTP, error)
}
本文件仅作包级占位;实际插件接口见 PluginRPC.go、pluginHTTP.go。
type Responser ¶
type Responser interface {
Write([]byte) (int, error) // 写入字节
WriteString(string) (int, error) // 写入字符串
ReadFrom(io.Reader) (int64, error) // 读取并写入
Redirect(string, int) // 转向
WriteHeader(int) // 状态码
Header() http.Header // 标头
Error(string, int) // 错误
Flush() // 刷新缓冲
Push(target string, opts *http.PushOptions) error // HTTP/2推送
Hijack() (net.Conn, *bufio.ReadWriter, error) // 劫持,能双向互相发送信息
}
Responser 类型定义。
type Route ¶
type Route struct {
HandlerError http.HandlerFunc // 错误访问处理
// contains filtered or unexported fields
}
Route 类型定义。
func (*Route) HandleFunc ¶
HandleFunc 绑定处理函数,匹配的网址支持正则,这说明你要严格的检查。
url string 网址,支持正则匹配 handler func(w ResponseWriter, r *Request) 处理函数
func (*Route) HandleFuncDot ¶
注册路径与 Handler。
func (*Route) ServeHTTP ¶
func (T *Route) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP 服务HTTP
w ResponseWriter 响应 r *Request 请求
func (*Route) SetSiteMan ¶
SetSiteMan 设置站点管理,将会携带在请求上下文中 siteMan *SiteMan 站点
type Router ¶ added in v3.0.3
type Router interface {
HandleFunc(url string, handler func(w http.ResponseWriter, r *http.Request))
HandleFuncDot(url string, handler ...func(Doter))
ServeHTTP(w http.ResponseWriter, r *http.Request)
}
路由注册与匹配。
type ServerHandlerDynamic ¶
type ServerHandlerDynamic struct {
// RootPath 网站根目录;PagePath 固定使用的页面路径(可选)
RootPath, PagePath string
// 可选的配置
Site *Site // 网站配置
Module func(name string) (DynamicTemplater, error) // 根据解析的首行识别动态文件类型对应的解释器
// 读取文件。仅在 .ServeHTTP 方法中使用,可外接特殊存储介质。
// - 非 nil 时:RootPath 视为逻辑前缀,filePath = path.Join(RootPath, pagePath);
// 不访问本地文件系统,不做符号链接校验;
// 仍对请求路径做字符串级 ".." 穿越检查,存储介质内的安全由 ReadFile 实现负责。
// 返回值中的 reader 必须非 nil(若只需探测 mtime 请仍返回一个可 Close 的空 reader,
// 或直接返回 io.NopCloser(bytes.NewReader(nil)))。
// - 为 nil 时走本地文件系统(os.Stat / os.OpenFile + 符号链接逃逸校验)。
ReadFile func(filePath string, u *url.URL) (io.ReadCloser, time.Time, error)
// contains filtered or unexported fields
}
ServerHandlerDynamic 处理动态页面文件并作缓存管理。
func (*ServerHandlerDynamic) Close ¶ added in v3.0.5
func (T *ServerHandlerDynamic) Close() error
Close 关闭整个处理器缓存释放相关持有资源。
func (*ServerHandlerDynamic) ServeHTTP ¶
func (T *ServerHandlerDynamic) ServeHTTP(rw http.ResponseWriter, req *http.Request)
ServeHTTP 服务 HTTP 请求
rw http.ResponseWriter 响应写入流 req *http.Request 当前客户端请求
ServeHTTP 服务 HTTP 请求。
type ServerHandlerStatic ¶
type ServerHandlerStatic struct {
RootPath, PagePath string
PageExpired int64 // 缓存过期时长(单位:秒),0则不缓存
}
ServerHandlerStatic 静态文件服务配置
func (*ServerHandlerStatic) ServeHTTP ¶
func (T *ServerHandlerStatic) ServeHTTP(rw http.ResponseWriter, req *http.Request)
ServeHTTP 实现 http.Handler 接口,处理文件读取与响应。
两阶段设计:
- os.Stat + 基础头 + 缓存协商:命中 304 直接返回,不 Open 文件;
- 未命中才 Open,并用 fstat 与第一阶段 Stat 对比;若文件在 Stat 与 Open 之间被替换(mtime/size 变化),用新 fileInfo 重做缓存协商与 Range 解析, 保证 Content-Length、ETag、Range 与正文读的是同一个文件版本(S1)。
type Session ¶
Session 会话用于用户保存数据。 内嵌 vmap.Map 提供线程安全的键值存储;id 由 Sessions 管理;exitCall 在 Free 时执行。
func (*Session) Defer ¶
Defer 在用户会话时间过期或被销毁后将被调用。
参数:
- call: 函数(任意可调用对象)
- args: 传给该函数的参数,或后续更多函数
返回:若会话已 Free 则返回 "has execute freed"
示例:
.Defer(fmt.Println, "1", "2") .Defer(fmt.Printf, "%s", "汉字")
func (*Session) Free ¶
func (T *Session) Free()
Free 执行结束 Defer 和键值有效期清理。 幂等:多次调用安全;设置 freed 后禁止再 Defer。
type Sessioner ¶
type Sessioner interface {
Token() string // 会话唯一编号(Cookie 值)
Set(key, val any) // 设置键值
Has(key any) bool // 是否存在键
Get(key any) any // 读取(不存在返回 nil)
GetHas(key any) (val any, ok bool) // 读取并判断是否存在
Del(key any) // 删除单键
Dels(keys []any) // 批量删除
SetExpired(key any, d time.Duration) // 为键设置过期时间
SetExpiredCall(key any, d time.Duration, f func(any)) // 过期时调用回调
TTL(key any) (time.Duration, bool) // 查询键剩余存活时间
Reset() // 清空所有键(触发过期清理)
Defer(call any, args ...any) error // 会话销毁时执行的延迟回调
}
Sessioner 用户独立的内存存储接口。 每个会话对应一个浏览器/客户端,可在请求间保存任意键值,并支持过期与退出回调。
典型用法:
sess := site.Sessions().Session(w, r)
sess.Set("user_id", 42)
if v, ok := sess.GetHas("user_id"); ok { ... }
type Sessions ¶
type Sessions struct {
Expired time.Duration // 保存 session 时间长
Name string // Cookie 名
Size int // 会话 ID 长度
Salt string // 加盐
// contains filtered or unexported fields
}
Sessions 管理不同用户的会话。
注意:内部含 sync.WaitGroup 与 vmap.Map,**不可按值复制**。
配置字段:
- Expired: 空闲过期时长(0 表示不过期)
- Name: Cookie 名称,如 "VID"
- Size: 会话 ID 字节长度(默认 64)
- Salt: 可选加盐,增加伪随机熵
示例:
ss := &Sessions{Expired: 20 * time.Minute, Name: "VID", Size: 64}
sess := ss.Session(w, r) // 自动读 Cookie 或新建并 Set-Cookie
func (*Sessions) CheckDeadAll ¶
CheckDeadAll 定时检查并清理过期会话;返回被删除的 id 列表。 在 Range 内只标记,Range 外再 Free,避免用户 Defer 回调死锁。
func (*Sessions) Configure ¶ added in v3.5.0
Configure 在写锁下更新配置(避免与 Get/Check 竞态)。
示例:ss.Configure(func(s *Sessions) { s.Expired = time.Hour })
func (*Sessions) DelSession ¶
DelSession 删除指定 id 的会话并 Free。
func (*Sessions) GetSession ¶
GetSession 使用 id 读取会话;过期则标记并异步 Free,返回 (nil, false)。 成功时会刷新 recent 时间戳。
func (*Sessions) InstantDeadAll ¶
func (T *Sessions) InstantDeadAll()
InstantDeadAll 立即清理全部会话,并异步执行各自的 Defer。
func (*Sessions) InstantDeadAllInto ¶ added in v3.3.0
InstantDeadAllInto 与 InstantDeadAll 相同,但把每个异步 Free 注册到调用方 wg。 SitePool.Close 用此等待最多 3 秒。
func (*Sessions) NewSession ¶
NewSession 按 id 新建或返回已有会话。
func (*Sessions) Session ¶
Session 是面向 Handler 的便捷入口: 1. 请求 Cookie 有效 → 复用; 2. 响应头已有同名 Set-Cookie → 复用; 3. 否则新建随机会话并写入 Set-Cookie。
返回 Sessioner;Name 为空时返回 nil。
type Site ¶
type Site struct {
RootDir func(path string) string // 网站的根目录解析
Extend vmap.Map // 用户自定义扩展数据
// contains filtered or unexported fields
}
Site 站点数据存储:会话集、全局 Map、根目录函数、扩展数据。
type SiteMan ¶
type SiteMan struct {
// contains filtered or unexported fields
}
SiteMan 按 Host 管理 *Site 的映射,支持贬域名(通配符)匹配。
type SitePool ¶
type SitePool struct {
// contains filtered or unexported fields
}
SitePool 网站池:按名称管理多个 *Site,并定期回收过期会话。
生命周期:
sp := NewSitePool()
site := sp.NewSite("default")
// ... 使用 site.Sessions() / site.Global()
sp.Close() // 停止 ticker、清理会话与全局数据
func (*SitePool) Close ¶
Close 关闭池:停止 ticker、清理全局/扩展数据、异步 Free 所有会话并等待最多 3 秒。 已关闭则返回 "SitePool is closed"。
func (*SitePool) NewSite ¶
NewSite 创建一个站点;若 name 已存在则返回已有实例。 Sessions 使用默认:Expired=20min, Name="VID", Size=64。
参数 name:站点标识(池内唯一) 返回:*Site(永不 nil)
示例:
site := pool.NewSite("blog")
func (*SitePool) RangeSite ¶
RangeSite 遍历池中所有站点;f 返回 false 时停止。
示例:
pool.RangeSite(func(name string, site *Site) bool {
fmt.Println(name, site.Sessions().Len())
return true
})
func (*SitePool) SetRecoverSession ¶
SetRecoverSession 设置回收无效会话的间隔。默认为 1 秒。 d <= 0 时强制为 1 秒,防止 ticker 高频空转打满 CPU。