| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619 |
- // 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
- }
|