Add WebDriver HTTP API with OpenAPI spec and selector-first extensions

[Copilot]

Implements W3C WebDriver-compatible HTTP API with Browser4's selector-first extensions. Skeleton implementation with in-memory mock storage—real browser integration deferred to follow-up PRs.

OpenAPI Specification

• openapi/openapi.yaml — OpenAPI 3.1 spec with W3C paths + selector-first endpoints
• Served at /openapi.yaml endpoint

Controllers (pulsar-rest/.../controller/webdriver/)

• SessionController — POST /session, GET/DELETE /session/{sessionId}
• NavigationController — POST/GET /session/{sessionId}/url, GET documentUri, baseUri
• SelectorController — /session/{sessionId}/selectors/{exists,waitFor,element,elements,click,fill,press,outerHtml,screenshot}
• ElementController — Standard WebDriver element operations (/element, /elements, /element/{id}/click|value|attribute|text)
• ScriptController — /session/{sessionId}/execute/{sync,async}
• ControlController — /session/{sessionId}/control/{delay,pause,stop}
• EventsController — /session/{sessionId}/event-configs, /events, /events/subscribe

DTOs & Service

• WebDriverDTOs.kt — Request/response types with W3C {"value": ...} wrapping
• WebDriverSessionService.kt — In-memory ConcurrentHashMap storage for sessions, elements, event configs

Example Usage

# Create session
curl -X POST http://localhost:8182/session \
  -H "Content-Type: application/json" \
  -d '{"capabilities": {"browserName": "chrome"}}'

# Selector-first click
curl -X POST http://localhost:8182/session/{sessionId}/selectors/click \
  -H "Content-Type: application/json" \
  -d '{"selector": "button.submit"}'

Tests

• 12 integration tests via MockMvc covering session lifecycle, navigation, selectors, elements, scripts, control, and events

Original prompt

目标：在 platonai/Browser4 仓库中新建分支并实现 WebDriver 兼容的 HTTP API（selector-first 扩展），包括 OpenAPI 描述文件与服务端骨架实现，以便后续迭代完成完整逻辑并生成多语言 SDK。

设计与约束（已与产品方确认）：

• 保持 W3C WebDriver 路径与响应包装（{"value": ...}），同时新增 selector-first endpoints（/session/{id}/selectors/...）。
• 使用自然 REST 命名，替代旧的 x-pulsar/* 路径。
• LoadOptions 与 PageEventHandlers 保持当前设计语义（支持通过 capabilities/payload 传入，提供 event-configs 与 events endpoints）。
• Selector 为一等公民：提供 selectors/* endpoints，同时保留标准 element-based endpoints。
• 该 PR 目标是创建 OpenAPI 文件并实现最小可运行的服务端骨架（控制器 + DTO + routing + simple in-memory handlers 返回 mock/placeholder 数据），不要求完成所有后端业务逻辑（实际浏览器交互留到后续 PR）。

Deliverables (在新分支 feature/openapi-webdriver-api 上创建一个 PR)：

1. 新增 OpenAPI spec: openapi/openapi.yaml — 使用先前生成的 OpenAPI 3.1 skeleton（包含 paths + components skeleton）。

2. 在 pulsar-rest 模块新增 Spring Boot 控制器与 DTO（Kotlin），提供以下最小实现：

   • SessionController: POST /session, DELETE /session/{sessionId}, GET /session/{sessionId}
   • NavigationController: POST /session/{sessionId}/url, GET /session/{sessionId}/url, GET /session/{sessionId}/documentUri, GET /session/{sessionId}/baseUri
   • SelectorController: POST /session/{sessionId}/selectors/exists, /waitFor, /element, /elements, /click, /fill, /press, /outerHtml, /screenshot
   • ElementController: POST /session/{sessionId}/element, /elements, POST /session/{sessionId}/element/{elementId}/click, /value, GET attribute/text
   • ScriptController: POST /session/{sessionId}/execute/sync and /async
   • ControlController: POST /session/{sessionId}/control/delay, /pause, /stop
   • EventsController: POST/GET /session/{sessionId}/event-configs, GET /session/{sessionId}/events, POST /session/{sessionId}/events/subscribe

   每个 controller 方法应：

   • 对请求体进行基本验证（非空等）。
   • 返回与 OpenAPI 中定义的响应 shape 对齐的 JSON（{"value": ...} 包装）。
   • 使用 in-memory maps to store sessions, elements, event-configs and subscriptions for the life of the application (no persistence required).
   • 对于 selectors endpoints，perform a simple CSS selector -> mocked elementId mapping (e.g., hash the selector string to generate element id) and return ElementRef accordingly.

3. DTOs and schemas: 在 pulsar-rest/src/main/kotlin/ai/platon/pulsar/rest/api/dto 中实现 Kotlin data classes for core schemas: NewSessionRequest/Response, SetUrlRequest, LoadOptions, SelectorRef, ElementRef, EventConfig, Event, ErrorResponse, etc. Ensure these map to OpenAPI types.

4. OpenAPI integration: expose the openapi.yaml via endpoint /openapi.yaml and provide basic Swagger UI configuration (optional) or a README note on how to load the spec.

5. Tests: add basic integration tests (Junit) in pulsar-rest/src/test that exercise a few endpoints (create session, navigate, selectors/exists, find element) verifying 200 and response shape. Tests may use MockMvc or WebTestClient.

6. CI/Build: ensure module builds; update pulsar-rest/pom.xml if necessary to include spring-boot-starter-web and jackson kotlin module, but avoid bumping versions. Use minimal dependencies.

Implementation notes for developer:

• Keep changes minimal and isolated to pulsar-rest and openapi/ files; avoid touching core logic modules.
• Use Kotlin idiomatic style consistent with repository (data classes, nullable types, require checks).
• Log incoming requests at debug level; add structured requestId in responses if possible.
• Document any deviations from the OpenAPI skeleton in the PR description.

Testing & Verification:

• The PR should compile and tests pass.
• The /openapi.yaml endpoint should serve the new spec file.
• Example curl flows should be included in PR description demonstrating session creation and selector-first click.

Please create a branch named feature/openapi-webdriver-api and open a pull request with the above changes. Include a clear PR description listing implemented endpoints, limitations (mock behavior), and next steps for completing real browser integration.

If any missing repository context prevents implementation (e.g., missing pulsar-rest module, incompatible build config), stop and report the blocking issue in the PR description.

This pull request was created as a result of the following prompt from Copilot chat.

目标：在 platonai/Browser4 仓库中新建分支并实现 WebDriver 兼容的 HTTP API（selector-first 扩展），包括 OpenAPI 描述文件与服务端骨架实现，以便后续迭代完成完整逻辑并生成多语言 SDK。

设计与约束（已与产品方确认）：

• 保持 W3C WebDriver 路径与响应包装（{"value": ...}），同时新增 selector-first endpoints（/session/{id}/selectors/...）。
• 使用自然 REST 命名，替代旧的 x-pulsar/* 路径。
• LoadOptions 与 PageEventHandlers 保持当前设计语义（支持通过 capabilities/payload 传入，提供 event-configs 与 events endpoints）。
• Selector 为一等公民：提供 selectors/* endpoints，同时保留标准 element-based endpoints。
• 该 PR 目标是创建 OpenAPI 文件并实现最小可运行的服务端骨架（控制器 + DTO + routing + simple in-memory handlers 返回 mock/placeholder 数据），不要求完成所有后端业务逻辑（实际浏览器交互留到后续 PR）。

Deliverables (在新分支 feature/openapi-webdriver-api 上创建一个 PR)：

1. 新增 OpenAPI spec: openapi/openapi.yaml — 使用先前生成的 OpenAPI 3.1 skeleton（包含 paths + components skeleton）。

2. 在 pulsar-rest 模块新增 Spring Boot 控制器与 DTO（Kotlin），提供以下最小实现：

   • SessionController: POST /session, DELETE /session/{sessionId}, GET /session/{sessionId}
   • NavigationController: POST /session/{sessionId}/url, GET /session/{sessionId}/url, GET /session/{sessionId}/documentUri, GET /session/{sessionId}/baseUri
   • SelectorController: POST /session/{sessionId}/selectors/exists, /waitFor, /element, /elements, /click, /fill, /press, /outerHtml, /screenshot
   • ElementController: POST /session/{sessionId}/element, /elements, POST /session/{sessionId}/element/{elementId}/click, /value, GET attribute/text
   • ScriptController: POST /session/{sessionId}/execute/sync and /async
   • ControlController: POST /session/{sessionId}/control/delay, /pause, /stop
   • EventsController: POST/GET /session/{sessionId}/event-configs, GET /session/{sessionId}/events, POST /session/{sessionId}/events/subscribe

   每个 controller 方法应：

   • 对请求体进行基本验证（非空等）。
   • 返回与 OpenAPI 中定义的响应 shape 对齐的 JSON（{"value": ...} 包装）。
   • 使用 in-memory maps to store sessions, elements, event-configs and subscriptions for the life of the application (no persistence required).
   • 对于 selectors endpoints，perform a simple CSS selector -> mocked elementId mapping (e.g., hash the selector string to generate element id) and return ElementRef accordingly.

3. DTOs and schemas: 在 pulsar-rest/src/main/kotlin/ai/platon/pulsar/rest/api/dto 中实现 Kotlin data classes for core schemas: NewSessionRequest/Response, SetUrlRequest, LoadOptions, SelectorRef, ElementRef, EventConfig, Event, ErrorResponse, etc. Ensure these map to OpenAPI types.

4. OpenAPI integration: expose the openapi.yaml via endpoint /openapi.yaml and provide basic Swagger UI configuration (optional) or a README note on how to load the spec.

5. Tests: add basic integration tests (Junit) in pulsar-rest/src/test that exercise a few endpoints (create session, navigate, selectors/exists, find element) verifying 200 and response shape. Tests may use MockMvc or WebTestClient.

6. CI/Build: ensure module builds; update pulsar-rest/pom.xml if necessary to include spring-boot-starter-web and jackson kotlin module, but avoid bumping versions. Use minimal dependencies.

Implementation notes for developer:

• Keep changes minimal and isolated to pulsar-rest and openapi/ files; avoid touching core logic modules.
• Use Kotlin idiomatic style consistent with repository (data classes, nullable types, require checks).
• Log incoming requests at debug level; add structured requestId in responses if possible.
• Document any deviations from the OpenAPI skeleton in the PR description.

Testing & Verification:

• The PR should compile and tests pass.
• The /openapi.yaml endpoint should serve the new spec file.
• Example curl flows should be included in PR description demonstrating session creation and selector-first click.

Please create a branch named feature/openapi-webdriver-api and open a pull request with the above changes. Include a clear PR description listing implemented endpoints, limitations (mock behavior), and next steps for completing real browser integration.

If any missing repository context prevents implementation (e.g., missing pulsar-rest module, incompatible build config), stop and report the blocking issue in the PR description.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.