// Package cfbrowser provides scoped browser sessions for trusted agent hosts. package cfbrowser import ( "context" "crypto/rand" "encoding/hex" "encoding/json" "errors" "os" "path/filepath" "sort" "sync" "time" "clusterflow.dev/cfbrowser/api" "clusterflow.dev/cfbrowser/internal/dom" "clusterflow.dev/cfbrowser/policy" ) type Config struct { DataDir string Executable string Headed bool // NoSandbox is an explicit escape hatch for isolated CI containers only. NoSandbox bool MaxSessions int MaxPages int MaxResultBytes int MaxDownloadBytes int64 Timeout time.Duration Policy policy.URLPolicy } func (c Config) normalized() (Config, error) { if c.MaxSessions == 0 { c.MaxSessions = 2 } if c.MaxPages == 0 { c.MaxPages = 3 } if c.MaxResultBytes == 0 { c.MaxResultBytes = 64 * 1024 } if c.MaxDownloadBytes == 0 { c.MaxDownloadBytes = 100 * 1024 * 1024 } if c.Timeout == 0 { c.Timeout = 30 * time.Second } if c.MaxSessions < 1 || c.MaxSessions > 32 || c.MaxPages < 1 || c.MaxPages > 16 || c.MaxResultBytes < 1024 || c.MaxResultBytes > 256*1024 || c.MaxDownloadBytes < 1 || c.MaxDownloadBytes > 2<<30 || c.Timeout < time.Millisecond || c.Timeout > 5*time.Minute { return c, api.Err("BROWSER_INVALID_CONFIG", "invalid resource limits") } return c, nil } type Manager struct { mu sync.Mutex cfg Config driver api.Driver sessions map[string]*session opening int closed bool ctx context.Context cancel context.CancelFunc root string removeRoot bool } type session struct { mu sync.Mutex info api.SessionInfo engine api.EngineSession pages map[string]*page files map[string]storedFile imported map[string]bool downloadDir string closed bool } type page struct { gate chan struct{} engine api.EnginePage id string snapshot string refs map[string]bool closed bool } func newID(prefix string) string { var b [16]byte if _, e := rand.Read(b[:]); e != nil { panic(e) } return prefix + hex.EncodeToString(b[:]) } func New(cfg Config, driver api.Driver) (*Manager, error) { if driver == nil { return nil, api.Err("BROWSER_INVALID_CONFIG", "driver is required") } cfg, err := cfg.normalized() if err != nil { return nil, err } root := cfg.DataDir temporary := false if root == "" { root, err = os.MkdirTemp("", "cfbrowser-") temporary = true } else { err = os.MkdirAll(root, 0700) } if err != nil { return nil, err } root, err = filepath.Abs(root) if err != nil { return nil, err } // Every manager gets a private instance directory, even with a shared data base. instance, err := os.MkdirTemp(root, "instance-") if err != nil { return nil, err } ctx, cancel := context.WithCancel(context.Background()) return &Manager{cfg: cfg, driver: driver, sessions: map[string]*session{}, ctx: ctx, cancel: cancel, root: instance, removeRoot: temporary}, nil } func (m *Manager) Capabilities(ctx context.Context) (api.Capabilities, error) { return m.driver.Probe(ctx) } func (m *Manager) operation(ctx context.Context) (context.Context, context.CancelFunc) { ctx, cancel := context.WithTimeout(ctx, m.cfg.Timeout) stop := context.AfterFunc(m.ctx, cancel) return ctx, func() { stop(); cancel() } } func (m *Manager) CreateSession(ctx context.Context, owner api.Owner) (api.SessionInfo, error) { if !owner.Valid() { return api.SessionInfo{}, api.Err("BROWSER_INVALID_OWNER", "environment, thread and run are required") } m.mu.Lock() if m.closed { m.mu.Unlock() return api.SessionInfo{}, api.Err("BROWSER_CLOSED", "manager is closed") } if len(m.sessions)+m.opening >= m.cfg.MaxSessions { m.mu.Unlock() return api.SessionInfo{}, api.Err("BROWSER_LIMIT", "session quota reached") } m.opening++ m.mu.Unlock() defer func() { m.mu.Lock(); m.opening--; m.mu.Unlock() }() id := newID("bs-") dir := filepath.Join(m.root, id) if err := os.Mkdir(dir, 0700); err != nil { return api.SessionInfo{}, err } ctx, cancel := m.operation(ctx) defer cancel() engine, err := m.driver.Open(ctx, api.EngineOptions{Headless: !m.cfg.Headed, Executable: m.cfg.Executable, NoSandbox: m.cfg.NoSandbox, DownloadDir: dir, ViewportWidth: 1280, ViewportHeight: 800, MaxDownloadBytes: m.cfg.MaxDownloadBytes}) if err != nil { _ = os.RemoveAll(dir) return api.SessionInfo{}, err } caps, err := m.driver.Probe(ctx) if err != nil { _ = engine.Close() _ = os.RemoveAll(dir) return api.SessionInfo{}, err } info := api.SessionInfo{ID: id, Owner: owner, Engine: caps.Engine, Pages: []string{}, Created: time.Now().UTC()} s := &session{info: info, engine: engine, pages: map[string]*page{}, files: map[string]storedFile{}, imported: map[string]bool{}, downloadDir: dir} m.mu.Lock() defer m.mu.Unlock() if m.closed || ctx.Err() != nil { _ = engine.Close() _ = os.RemoveAll(dir) return api.SessionInfo{}, api.Err("BROWSER_CLOSED", "session creation was canceled") } m.sessions[id] = s return info, nil } func (m *Manager) owned(owner api.Owner, id string) (*session, error) { m.mu.Lock() defer m.mu.Unlock() s := m.sessions[id] if m.closed { return nil, api.Err("BROWSER_CLOSED", "manager is closed") } if s == nil || !owner.Valid() || s.info.Owner != owner { return nil, api.Err("BROWSER_SCOPE_MISMATCH", "session is not owned by this run") } return s, nil } func (m *Manager) Sessions(owner api.Owner) []api.SessionInfo { m.mu.Lock() defer m.mu.Unlock() out := []api.SessionInfo{} for _, s := range m.sessions { if s.info.Owner == owner { s.mu.Lock() v := s.info v.Pages = make([]string, 0, len(s.pages)) for id := range s.pages { v.Pages = append(v.Pages, id) } sort.Strings(v.Pages) s.mu.Unlock() out = append(out, v) } } sort.Slice(out, func(i, j int) bool { return out[i].ID < out[j].ID }) return out } func (m *Manager) NewPage(ctx context.Context, owner api.Owner, id string) (api.PageInfo, error) { s, err := m.owned(owner, id) if err != nil { return api.PageInfo{}, err } s.mu.Lock() defer s.mu.Unlock() if s.closed { return api.PageInfo{}, api.Err("BROWSER_CLOSED", "session is closed") } if len(s.pages) >= m.cfg.MaxPages { return api.PageInfo{}, api.Err("BROWSER_LIMIT", "page quota reached") } ctx, cancel := m.operation(ctx) defer cancel() p, err := s.engine.NewPage(ctx) if err != nil { return api.PageInfo{}, err } pid := newID("pg-") s.pages[pid] = &page{id: pid, engine: p, gate: make(chan struct{}, 1)} return api.PageInfo{SessionID: id, PageID: pid}, nil } func (m *Manager) lockedPage(ctx context.Context, owner api.Owner, sid, pid string) (*page, func(), error) { s, err := m.owned(owner, sid) if err != nil { return nil, nil, err } s.mu.Lock() p := s.pages[pid] closed := s.closed s.mu.Unlock() if p == nil || closed { return nil, nil, api.Err("BROWSER_PAGE_NOT_FOUND", "page is unavailable") } select { case p.gate <- struct{}{}: case <-ctx.Done(): return nil, nil, ctx.Err() case <-m.ctx.Done(): return nil, nil, api.Err("BROWSER_CLOSED", "manager is closed") } unlock := func() { <-p.gate } if p.closed { unlock() return nil, nil, api.Err("BROWSER_CLOSED", "page is closed") } return p, unlock, nil } func (m *Manager) Navigate(ctx context.Context, o api.Owner, sid, pid, url, op string) (api.PageInfo, error) { ctx, cancel := m.operation(ctx) defer cancel() if op == "" { op = "goto" } if op != "goto" && op != "back" && op != "forward" && op != "reload" { return api.PageInfo{}, api.Err("BROWSER_INVALID_ARGUMENT", "invalid navigation operation") } if op == "goto" { var err error url, err = m.cfg.Policy.Validate(ctx, url) if err != nil { return api.PageInfo{}, err } } p, unlock, err := m.lockedPage(ctx, o, sid, pid) if err != nil { return api.PageInfo{}, err } defer unlock() p.snapshot = "" p.refs = nil result, err := p.engine.Navigate(ctx, url, op) return api.PageInfo{SessionID: sid, PageID: pid, URL: result}, err } func decode(raw json.RawMessage, out any) error { var status struct { Error string `json:"error"` } if err := json.Unmarshal(raw, &status); err == nil && status.Error != "" { return api.Err(status.Error, "page operation could not be completed") } if len(raw) > 512*1024 { return api.Err("BROWSER_RESULT_LIMIT", "engine result exceeds 512 KiB") } return json.Unmarshal(raw, out) } func evaluate(ctx context.Context, p *page, op string, args any, out any) error { raw, err := p.engine.Evaluate(ctx, dom.Script(op, args)) if err != nil { return err } return decode(raw, out) } func (m *Manager) Snapshot(ctx context.Context, o api.Owner, sid, pid string, r api.SnapshotRequest) (api.Snapshot, error) { if r.Mode == "" { r.Mode = "compact" } if r.Mode != "compact" && r.Mode != "interactive" { return api.Snapshot{}, api.Err("BROWSER_INVALID_ARGUMENT", "mode must be compact or interactive") } limit := m.budget(r.MaxBytes) if limit < 1024 { return api.Snapshot{}, api.Err("BROWSER_INVALID_ARGUMENT", "snapshot budget must be at least 1024 bytes") } if r.MaxElements == 0 { r.MaxElements = 150 } if r.MaxElements < 1 || r.MaxElements > 150 { return api.Snapshot{}, api.Err("BROWSER_INVALID_ARGUMENT", "maxElements must be 1..150") } ctx, cancel := m.operation(ctx) defer cancel() p, unlock, err := m.lockedPage(ctx, o, sid, pid) if err != nil { return api.Snapshot{}, err } defer unlock() id := newID("sn-") var result api.Snapshot err = evaluate(ctx, p, "snapshot", map[string]any{"id": id, "mode": r.Mode, "maxElements": r.MaxElements, "textLimit": limit / 4}, &result) if err != nil { return result, err } result.PageID = pid if result.SnapshotID != id { return api.Snapshot{}, api.Err("BROWSER_INVALID_RESULT", "snapshot ID mismatch") } if err = fitSnapshot(&result, limit); err != nil { return result, err } p.snapshot = id p.refs = map[string]bool{} for _, e := range result.Elements { p.refs[e.Ref] = true } return result, nil } func (m *Manager) budget(n int) int { if n <= 0 || n > m.cfg.MaxResultBytes { return m.cfg.MaxResultBytes } return n } func fitSnapshot(s *api.Snapshot, limit int) error { for { b, err := json.Marshal(s) if err != nil { return err } if len(b) <= limit { return nil } s.Truncated = true if len(s.Text) > 0 { s.Text = truncate(s.Text, len(s.Text)/2) continue } if len(s.Elements) > 0 { s.Elements = s.Elements[:len(s.Elements)-1] continue } if len(s.Title) > 64 { s.Title = truncate(s.Title, 64) continue } if len(s.URL) > 128 { s.URL = truncate(s.URL, 128) continue } return api.Err("BROWSER_RESULT_LIMIT", "budget cannot hold snapshot metadata") } } func truncate(s string, n int) string { if n >= len(s) { return s } if n < 0 { n = 0 } for n > 0 && n < len(s) && s[n]&0xc0 == 0x80 { n-- } return s[:n] } func (m *Manager) Act(ctx context.Context, o api.Owner, sid, pid string, r api.ActionRequest) (api.ActionResult, error) { if err := api.ValidateAction(r); err != nil { return api.ActionResult{Effect: "not_dispatched"}, err } ctx, cancel := m.operation(ctx) defer cancel() p, unlock, err := m.lockedPage(ctx, o, sid, pid) if err != nil { return api.ActionResult{}, err } defer unlock() if p.snapshot != r.SnapshotID || !p.refs[r.Ref] { return api.ActionResult{Effect: "not_dispatched"}, api.Err("BROWSER_STALE_REF", "take a new snapshot") } var target struct { X, Y float64 Value, Tag, Type string Checked bool ReadOnly bool } if err = evaluate(ctx, p, "prepare", r, &target); err != nil { return api.ActionResult{Effect: "not_dispatched"}, err } caps, err := m.driver.Probe(ctx) if err != nil { return api.ActionResult{}, err } trusted := caps.Supports("trustedInput") kind := "synthetic" dispatched := false if trusted && (r.Action == "click" || r.Action == "hover" || r.Action == "type" || r.Action == "press" || r.Action == "fill") { kind = "browser" value := r.Value action := r.Action if action == "fill" && (target.Tag != "INPUT" && target.Tag != "TEXTAREA" || target.Type == "file" || target.ReadOnly) { return api.ActionResult{Effect: "not_dispatched"}, api.Err("BROWSER_TARGET_NOT_ACTIONABLE", "fill requires a text input") } dispatched = true err = p.engine.Input(ctx, action, value, target.X, target.Y) } else { var result map[string]any dispatched = true err = evaluate(ctx, p, "mutation", r, &result) } if err != nil { var typed *api.Error if errors.As(err, &typed) && (typed.Code == "BROWSER_STALE_REF" || typed.Code == "BROWSER_TARGET_NOT_ACTIONABLE" || typed.Code == "BROWSER_INVALID_ARGUMENT" || typed.Code == "BROWSER_CAPABILITY_UNSUPPORTED") { return api.ActionResult{Effect: "not_dispatched", InputKind: kind}, err } if dispatched { return api.ActionResult{Effect: "unknown", InputKind: kind}, &api.Error{Code: "BROWSER_ACTION_OUTCOME_UNKNOWN", Message: "observe the page before retrying", Effect: "unknown"} } } return api.ActionResult{Effect: "dispatched", InputKind: kind}, err } func (m *Manager) Read(ctx context.Context, o api.Owner, sid, pid string, r api.ReadRequest) (api.ReadResult, error) { if r.Mode == "" { r.Mode = "text" } if r.Mode != "text" && r.Mode != "table" { return api.ReadResult{}, api.Err("BROWSER_INVALID_ARGUMENT", "read mode must be text or table") } limit := m.budget(r.MaxBytes) if limit < 256 { return api.ReadResult{}, api.Err("BROWSER_INVALID_ARGUMENT", "read budget must be at least 256 bytes") } ctx, cancel := m.operation(ctx) defer cancel() p, unlock, err := m.lockedPage(ctx, o, sid, pid) if err != nil { return api.ReadResult{}, err } defer unlock() if r.Ref != "" && (p.snapshot != r.SnapshotID || !p.refs[r.Ref]) { return api.ReadResult{}, api.Err("BROWSER_STALE_REF", "take a new snapshot") } var result api.ReadResult err = evaluate(ctx, p, "read", map[string]any{"snapshotId": r.SnapshotID, "ref": r.Ref, "mode": r.Mode, "limit": limit / 4}, &result) if err != nil { return result, err } for { b, _ := json.Marshal(result) if len(b) <= limit { break } result.Truncated = true if len(result.Text) > 0 { result.Text = truncate(result.Text, len(result.Text)/2) } else if len(result.Rows) > 0 { result.Rows = result.Rows[:len(result.Rows)-1] } else if len(result.URL) > 64 { result.URL = truncate(result.URL, 64) } else { return result, api.Err("BROWSER_RESULT_LIMIT", "read metadata exceeds budget") } } return result, nil } func (m *Manager) Wait(ctx context.Context, o api.Owner, sid, pid string, r api.WaitRequest) error { if r.Kind != "ready" && r.Kind != "url" && r.Kind != "text" && r.Kind != "textGone" { return api.Err("BROWSER_INVALID_ARGUMENT", "unsupported wait condition") } if len(r.Value) > 8192 || r.TimeoutMS < 0 || r.TimeoutMS > 300000 { return api.Err("BROWSER_INVALID_ARGUMENT", "invalid wait value or timeout") } ctx, cancel := m.operation(ctx) defer cancel() if r.TimeoutMS > 0 { var stop context.CancelFunc ctx, stop = context.WithTimeout(ctx, time.Duration(r.TimeoutMS)*time.Millisecond) defer stop() } p, unlock, err := m.lockedPage(ctx, o, sid, pid) if err != nil { return err } defer unlock() ticker := time.NewTicker(50 * time.Millisecond) defer ticker.Stop() for { var ok bool raw, e := p.engine.Evaluate(ctx, dom.Script("wait", r)) if e != nil { return e } if e = json.Unmarshal(raw, &ok); e != nil { return e } if ok { return nil } select { case <-ctx.Done(): return ctx.Err() case <-ticker.C: } } } func (m *Manager) CloseSession(o api.Owner, id string) error { s, err := m.owned(o, id) if err != nil { return err } m.mu.Lock() delete(m.sessions, id) m.mu.Unlock() return errors.Join(s.close(), os.RemoveAll(s.downloadDir)) } func (m *Manager) ClosePage(ctx context.Context, o api.Owner, sid, pid string) error { ctx, cancel := m.operation(ctx) defer cancel() p, unlock, err := m.lockedPage(ctx, o, sid, pid) if err != nil { return err } defer unlock() s, err := m.owned(o, sid) if err != nil { return err } s.mu.Lock() delete(s.pages, pid) s.mu.Unlock() p.closed = true p.refs = nil p.snapshot = "" return p.engine.Close() } func (s *session) close() error { s.mu.Lock() defer s.mu.Unlock() if s.closed { return nil } s.closed = true return s.engine.Close() } func (m *Manager) Close() error { m.mu.Lock() if m.closed { m.mu.Unlock() return nil } m.closed = true m.cancel() sessions := m.sessions m.sessions = map[string]*session{} m.mu.Unlock() var result error for _, s := range sessions { result = errors.Join(result, s.close()) } result = errors.Join(result, os.RemoveAll(m.root)) if m.removeRoot { result = errors.Join(result, os.Remove(filepath.Dir(m.root))) } return result }