@things-factory/integration-headless 8.0.0-beta.9 → 8.0.0

package/helps/integration/connector/headless-connector.zh.md

@@ -1,168 +1,57 @@
-### 🏆 无头连接器 (Headless Connector)
+### 无头浏览器池连接器 (Headless Pool Connector)
 
-**无头连接器** 利用无头浏览器执行 **自动登录**、**网页爬取**、**PDF 生成**、**表单提交**等任务。  
-它可以管理多个浏览器会话，支持会话保持、Cookie 处理、基于 API 的登录等功能。
+**无头浏览器池连接器**旨在管理无头浏览器实例的池。该连接器在执行需要多个无头浏览器会话同时运行的任务时非常有用，例如生成PDF或进行网页抓取。它能够有效地管理这些无头浏览器实例的创建、使用和销毁。
 
----
+#### 端点
 
-## 🚀 1. 端点（Endpoint）
+`无头浏览器池连接器`不要求特定的端点，但可以作为连接设置的一部分提供URI。此URI通常作为占位符使用，池在内部处理实际连接。也就是说，端点可以输入任意字符串。
 
-无头连接器的端点需要填写 **目标网页的 URL**。  
-例如，可以输入 `https://example.com` 以抓取该网站的内容，或者使用 `localhost` 生成 PDF。
+#### 参数
 
----
+- **min** (数字):
+  - 指定池中维持的最少无头浏览器实例数量。
+  - 默认值: `2`
+- **max** (数字):
+  - 指定池中可以处理的最大无头浏览器实例数量。
+  - 默认值: `10`
 
-## 🔧 2. 参数（Parameters）
+这些参数允许根据预期的工作负载调整池的大小。例如，如果应用程序经常同时需要多个浏览器实例，则可以增加`max`值。
 
-### ✅ 登录相关配置
-
-| 参数                 | 类型     | 描述                                         | 默认值        |
-| -------------------- | -------- | -------------------------------------------- | ------------- |
-| `username`           | `string` | 登录用户名（账户名）                         | `""`          |
-| `password`           | `string` | 登录密码                                     | `""`          |
-| `loginPagePath`      | `string` | 登录页面路径（如 `/login`）                  | `"/login"`    |
-| `loginApiUrl`        | `string` | 登录 API 端点（如果没有则 `null`）           | `null`        |
-| `usernameSelector`   | `string` | 登录表单的用户名输入框 CSS 选择器            | `"#username"` |
-| `passwordSelector`   | `string` | 登录表单的密码输入框 CSS 选择器              | `"#password"` |
-| `submitSelector`     | `string` | 登录按钮的 CSS 选择器                        | `"#submit"`   |
-| `successSelector`    | `string` | 用于判断登录成功的元素 CSS 选择器            | `null`        |
-| `shadowDomSelectors` | `string` | 处理 Shadow DOM 内部元素的选择器（逗号分隔） | `""`          |
-| `timeout`            | `number` | 登录及页面加载的超时时间（毫秒）             | `15000`       |
-| `retries`            | `number` | 登录重试次数                                 | `3`           |
-
----
-
-## 🔍 3. `loginApiUrl` 参数的详细说明
-
-### 🔹 `loginApiUrl` 是什么？
-
-`loginApiUrl` 是指用于网站 **API 登录** 的接口地址。如果网站不使用 API 方式登录，则不需要设置此参数。
-
-### ✅ `loginApiUrl` 为空 (`null`)
-
-此时 **使用 HTML 表单提交的方式进行登录**。  
-无头浏览器会直接模拟用户操作，如填写用户名和密码，并点击提交按钮。
-
-#### 📌 示例（HTML 表单登录）
+#### 设置示例
 
 ```json
 {
-  "endpoint": "https://example.com",
-  "params": {
-    "username": "user123",
-    "password": "securepassword",
-    "loginPagePath": "/login",
-    "usernameSelector": "#username",
-    "passwordSelector": "#password",
-    "submitSelector": "#submit-button",
-    "successSelector": ".dashboard"
-  }
-}
-```
-
-#### 🛠 处理过程：
-
-1. 访问 `https://example.com/login`
-2. 在 `#username` 和 `#password` 输入框中填入账户信息
-3. 点击 `#submit-button` 提交表单
-4. 通过 `.dashboard` 元素是否存在来判断是否登录成功
-
----
-
-### ✅ `loginApiUrl` 设定时
-
-如果目标网站使用 **API 方式登录**，则 `loginApiUrl` 需要设置为该 API 的地址。  
-例如，如果 API 登录地址是 `/api/auth/login`，则需要手动设置该参数。
-
-#### 📌 示例（API 登录方式）
-
-```json
-{
-  "endpoint": "https://example.com",
-  "params": {
-    "username": "user123",
-    "password": "securepassword",
-    "loginPagePath": "/login",
-    "loginApiUrl": "/api/auth/login",
-    "usernameSelector": "#username",
-    "passwordSelector": "#password",
-    "submitSelector": "#submit-button",
-    "successSelector": ".dashboard"
-  }
-}
-```
-
-#### 🛠 处理过程：
-
-1. 发送 **HTTP POST 请求** 到 `https://example.com/api/auth/login`
-2. 服务器返回成功响应，浏览器存储会话 Cookie
-3. 访问主页面并检查 `.dashboard` 是否存在，以确认登录成功
-
----
-
-## 🏗 4. 配置示例
-
-```json
-{
-  "name": "headless-browser-connector",
+  "name": "headless-browser-pool",
   "connector": "headless-connector",
-  "endpoint": "https://example.com",
+  "endpoint": "1",
   "params": {
-    "username": "user123",
-    "password": "securepassword",
-    "loginPagePath": "/login",
-    "loginApiUrl": "/api/auth/login",
-    "usernameSelector": "#username",
-    "passwordSelector": "#password",
-    "submitSelector": "#submit",
-    "successSelector": ".dashboard",
-    "timeout": 20000,
-    "retries": 5
+    "min": 5,
+    "max": 20
   }
 }
 ```
 
----
-
-## 🔄 5. 连接生命周期（Connection Lifecycle）
-
-- **connect**
+在上述示例中，池至少保持5个无头浏览器实例，并且在需要时可以扩展到最多20个实例。
 
-  - 根据参数执行登录流程，并保持会话。
-  - 存储 Cookie，以便后续请求使用。
+#### 连接生命周期
 
-- **disconnect**
-  - 关闭浏览器会话，并清除 Cookie。
+- **connect**:
 
----
+  - 初始化连接，根据设定的参数(`min` 和 `max`)创建无头浏览器实例池。
+  - 池会自动管理这些实例的生命周期，必要时创建新的实例并重用现有的实例。
 
-## ⚡ 6. 支持的任务（Supported Tasks）
+- **disconnect**:
+  - 销毁无头浏览器池，确保所有实例都被适当关闭并释放资源。
 
-| 任务类型               | 描述                   |
-| ---------------------- | ---------------------- |
-| `headless-pdf-capture` | 将 HTML 转换为 PDF     |
-| `headless-scrap`       | 网页爬取，提取特定数据 |
-| `headless-post`        | 自动填写表单并提交     |
+#### 使用场景
 
-#### 📌 任务示例
+`无头浏览器池连接器`主要用于需要在无头浏览器环境中执行任务的场景。例如，生成HTML内容的PDF、捕获网页截图或从网站抓取数据。
 
-### 1️⃣ 网页爬取（`headless-scrap`）
+#### 支持的任务
 
-```json
-{
-  "name": "scrape-data",
-  "taskType": "headless-scrap",
-  "params": {
-    "path": "/products",
-    "selectors": [
-      { "text": "商品名称", "value": ".product-title" },
-      { "text": "价格", "value": ".product-price" }
-    ]
-  }
-}
-```
+`无头浏览器池连接器`支持以 `headless-pdf` 为前缀的任务。这些任务将使用由此连接器管理的无头浏览器实例。
 
-### 2️⃣ PDF 生成（`headless-pdf-capture`）
+#### 任务示例使用
 
 ```json
 {
@@ -177,42 +66,6 @@
 }
 ```
 
-### 3️⃣ 表单提交（`headless-post`）
-
-```json
-{
-  "name": "submit-form",
-  "taskType": "headless-post",
-  "params": {
-    "formPath": "/contact",
-    "fields": {
-      "#name": "张三",
-      "#email": "zhangsan@example.com",
-      "#message": "你好，我想咨询一下！"
-    },
-    "submitSelector": "#submit-button"
-  }
-}
-```
-
----
-
-## 📢 7. 说明（Description）
-
-**无头连接器** 可用于 **自动化网页爬取、PDF 生成、表单提交** 等任务。  
-它支持 **HTML 登录** 和 **API 登录**，适用于各种不同的网页登录方式。
-
----
-
-### 📌 功能总结
-
-| 功能              | 说明                                 |
-| ----------------- | ------------------------------------ |
-| **HTML 表单登录** | 直接模拟用户操作（适用于大部分网页） |
-| **API 登录**      | 通过 API 发送登录请求（更快）        |
-| **会话保持**      | 存储 Cookie 并维持登录状态           |
-| **网页爬取**      | 提取页面中的特定数据                 |
-| **PDF 生成**      | 将 HTML 页面转换为 PDF               |
-| **表单提交**      | 自动填充并提交表单                   |
+#### 说明
 
-📌 **通过无头连接器，你可以轻松地在不同网站上实现自动化操作！** 🚀
+**无头浏览器池连接器**通过高效管理无头浏览器实例池，确保在高需求场景下执行PDF生成和网页抓取等任务时，资源利用的优化和可扩展性。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/integration-headless",
-  "version": "8.0.0-beta.9",
+  "version": "8.0.0",
   "main": "dist-server/index.js",
   "things-factory": true,
   "author": "heartyoh <heartyoh@hatiolab.com>",
@@ -22,12 +22,12 @@
     "clean": "npm run clean:server"
   },
   "dependencies": {
-    "@things-factory/attachment-base": "^8.0.0-beta.9",
-    "@things-factory/board-service": "^8.0.0-beta.9",
-    "@things-factory/integration-base": "^8.0.0-beta.9",
-    "@things-factory/shell": "^8.0.0-beta.9",
+    "@things-factory/attachment-base": "^8.0.0",
+    "@things-factory/board-service": "^8.0.0",
+    "@things-factory/integration-base": "^8.0.0",
+    "@things-factory/shell": "^8.0.0",
     "ejs": "^3.1.10",
     "pdf-lib": "^1.17.1"
   },
-  "gitHead": "86b1dfa26292926a2d5447fdc23bfa5a9e983245"
+  "gitHead": "07ef27d272dd9a067a9648ac7013748510556a18"
 }

package/server/engine/connector/headless-connector.ts

@@ -0,0 +1,68 @@
+import { ConnectionManager, Connector } from '@things-factory/integration-base'
+import { createHeadlessPool, destroyHeadlessPool } from './headless-pool'
+
+export class HeadlessConnector implements Connector {
+  async ready(connectionConfigs) {
+    await Promise.all(connectionConfigs.map(this.connect.bind(this)))
+
+    ConnectionManager.logger.info('headless-connector connections are ready')
+  }
+
+  async connect(connection) {
+    var {
+      endpoint: uri = '1',
+      params: { min = 2, max = 10 }
+    } = connection
+
+    const headlessPool = createHeadlessPool({
+      min,
+      max,
+      testOnBorrow: true,
+      acquireTimeoutMillis: 15000
+    })
+
+    ConnectionManager.addConnectionInstance(connection, headlessPool)
+
+    ConnectionManager.logger.info(
+      `headless-connector connection(${connection.name}:${connection.endpoint}) is connected`
+    )
+  }
+
+  async disconnect(connection) {
+    const headlessPool = ConnectionManager.getConnectionInstance(connection)
+    destroyHeadlessPool(headlessPool)
+
+    ConnectionManager.removeConnectionInstance(connection)
+
+    ConnectionManager.logger.info(`headless-connector connection(${connection.name}) is disconnected`)
+  }
+
+  get parameterSpec() {
+    return [
+      {
+        type: 'number',
+        name: 'min',
+        label: 'pool-size-min'
+      },
+      {
+        type: 'number',
+        name: 'max',
+        label: 'pool-size-max'
+      }
+    ]
+  }
+
+  get taskPrefixes() {
+    return ['headless-pdf']
+  }
+
+  get description() {
+    return 'Headless Pool Connector'
+  }
+
+  get help() {
+    return 'integration/connector/headless-connector'
+  }
+}
+
+ConnectionManager.registerConnector('headless-connector', new HeadlessConnector())

package/server/engine/connector/headless-pool.ts

@@ -0,0 +1,69 @@
+import * as genericPool from 'generic-pool'
+
+import { config, logger } from '@things-factory/env'
+
+try {
+  var puppeteer = require('puppeteer')
+} catch (err) {
+  logger.error(err)
+}
+
+export function createHeadlessPool(options: genericPool.Options) {
+  return genericPool.createPool(
+    {
+      create() {
+        console.log('headless instance in headless-pool-integration about to create')
+        return initializeChromium()
+      },
+      validate(browser) {
+        return Promise.race([
+          new Promise(res => setTimeout(() => res(false), 1500)),
+          browser
+            //@ts-ignore
+            .version()
+            .then(_ => true)
+            .catch(_ => false)
+        ])
+      },
+      destroy(browser) {
+        //@ts-ignore
+        return browser.close()
+      }
+    } as genericPool.Factory<any>,
+    options
+  )
+}
+
+export async function destroyHeadlessPool(headlessPool: genericPool.Pool<any>) {
+  if (headlessPool) {
+    console.log('headless-pool-integration about to destroy')
+
+    await headlessPool.drain()
+    await headlessPool.clear()
+  }
+}
+
+const CHROMIUM_PATH = config.get('CHROMIUM_PATH')
+
+async function initializeChromium() {
+  try {
+    if (!puppeteer) {
+      return
+    }
+
+    var launchSetting = {
+      args: ['--hide-scrollbars', '--mute-audio', '--no-sandbox', '--use-gl=egl'],
+      headless: 'shell'
+    }
+
+    if (CHROMIUM_PATH) {
+      launchSetting['executablePath'] = CHROMIUM_PATH
+    }
+
+    const browser = await puppeteer.launch(launchSetting)
+
+    return browser
+  } catch (err) {
+    logger.error(err)
+  }
+}

package/server/engine/connector/index.ts

@@ -0,0 +1 @@
+import './headless-connector'

package/server/engine/index.ts

@@ -0,0 +1,2 @@
+import './connector'
+import './task'

package/server/engine/task/headless-pdf-capture-board.ts

@@ -0,0 +1,182 @@
+import { TaskRegistry } from '@things-factory/integration-base'
+import { PDFCaptureUtil, getCommonParameterSpec } from './pdf-capture-util'
+import { BoardFunc } from '@things-factory/board-service'
+import { access } from '@things-factory/utils'
+
+const PAGE_FORMATS = {
+  A4: { width: 595.28, height: 841.89 },
+  A3: { width: 841.89, height: 1190.55 },
+  Letter: { width: 612, height: 792 },
+  Legal: { width: 612, height: 1008 }
+}
+
+function convertToPixels(value: string): number {
+  const dpi = 96 // PDF에서 기본적으로 사용하는 DPI
+
+  if (value.endsWith('px')) {
+    return parseFloat(value)
+  } else if (value.endsWith('in')) {
+    const inches = parseFloat(value)
+    return inches * dpi
+  } else if (value.endsWith('cm')) {
+    const cm = parseFloat(value)
+    return cm * (dpi / 2.54)
+  }
+
+  return 0
+}
+
+export async function HeadlessPDFCaptureBoard(step, context) {
+  const pdfUtil = new PDFCaptureUtil(context)
+  await pdfUtil.initBrowser(step.connection)
+
+  try {
+    var {
+      board: boardObject,
+      accessor,
+      boardAccessor,
+      draft,
+      format = 'A4',
+      width,
+      height,
+      landscape,
+      marginLeft = 0,
+      marginRight = 0,
+      marginTop = 0,
+      marginBottom = 0
+    } = step.params
+    var { domain, data, user, logger } = context
+
+    const boardId = boardAccessor ? access(boardAccessor, data) : boardObject?.id
+
+    if (!boardId) {
+      throw new Error('The board property must be set')
+    }
+
+    const boardInput = access(accessor, data)
+
+    const { model, base } = await BoardFunc.headlessModel({ domain, id: boardId }, draft)
+    const [fontsToUse, fontStyles] = await BoardFunc.fonts(domain)
+
+    model.fonts = fontsToUse
+    model.fontStyles = fontStyles
+
+    var widthN = width ? convertToPixels(width) : 0
+    var heightN = height ? convertToPixels(height) : 0
+
+    if (!widthN && !heightN && PAGE_FORMATS[format]) {
+      const pageDimensions = PAGE_FORMATS[format]
+      widthN = pageDimensions.width * (96 / 72)
+      heightN = pageDimensions.height * (96 / 72)
+    }
+
+    if (landscape && widthN && heightN) {
+      ;[widthN, heightN] = [heightN, widthN]
+    }
+
+    marginLeft = convertToPixels(marginLeft)
+    marginTop = convertToPixels(marginTop)
+    marginBottom = convertToPixels(marginBottom)
+    marginRight = convertToPixels(marginRight)
+
+    const contentWidth = widthN - marginLeft - marginRight
+    const contentHeight = heightN - marginTop - marginBottom
+
+    const page = await pdfUtil.browser!.newPage()
+
+    await page.setViewport({ width: Math.round(contentWidth), height: Math.round(contentHeight) })
+    await page.setRequestInterception(true)
+    await page.setDefaultTimeout(10000)
+
+    page.on('console', async msg => {
+      console.log(`[browser ${msg.type()}] ${msg.text()}`)
+    })
+
+    page.on('requestfailed', request => {
+      console.log('Request failed:', request.url())
+    })
+
+    const protocol = 'http'
+    const host = 'localhost'
+    const port = process.env.PORT ? `:${process.env.PORT}` : ''
+    const path = '/internal-board-service-view'
+    const url = `${protocol}://${host}${port}${path}`
+
+    const token = await user?.sign()
+
+    page.on('request', request => {
+      if (request.url() === url) {
+        request.continue({
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'x-things-factory-domain': domain?.subdomain,
+            Authorization: 'Bearer ' + token
+          },
+          postData: JSON.stringify({
+            model,
+            base
+          })
+        })
+      } else if (request.url().startsWith(`${protocol}://${host}${port}`)) {
+        request.continue({
+          headers: {
+            ...request.headers(),
+            'x-things-factory-domain': domain?.subdomain,
+            Authorization: 'Bearer ' + token
+          }
+        })
+      } else {
+        request.continue()
+      }
+    })
+
+    await page.goto(url)
+
+    await page.evaluate(data => {
+      //@ts-ignore
+      s.data = data
+      return new Promise(resolve => {
+        requestAnimationFrame(() => resolve(0))
+      })
+    }, boardInput)
+
+    await pdfUtil.processPageAndGeneratePDF(step.params, null, page)
+
+    return {
+      data: context.__headless_pdf
+    }
+  } catch (error) {
+    throw error
+  } finally {
+    await pdfUtil.closeBrowser()
+  }
+}
+
+HeadlessPDFCaptureBoard.parameterSpec = [
+  ...getCommonParameterSpec(),
+  {
+    type: 'string',
+    name: 'boardAccessor',
+    label: 'board-accessor'
+  },
+  {
+    type: 'resource-object',
+    name: 'board',
+    label: 'board',
+    property: {
+      queryName: 'boards'
+    }
+  },
+  {
+    type: 'boolean',
+    name: 'draft',
+    label: 'board-draft',
+    defaultValue: false,
+    description: 'Set whether to get the current working version or the last released version'
+  }
+]
+
+HeadlessPDFCaptureBoard.help = 'integration/task/headless-pdf-capture-board'
+
+TaskRegistry.registerTaskHandler('headless-pdf-capture-board', HeadlessPDFCaptureBoard)

package/server/engine/task/headless-pdf-capture-markdown.ts

@@ -0,0 +1,47 @@
+import { TaskRegistry } from '@things-factory/integration-base'
+import { access } from '@things-factory/utils'
+import { marked } from 'marked'
+
+import { PDFCaptureUtil, getCommonParameterSpec } from './pdf-capture-util'
+
+export async function HeadlessPDFCaptureMarkdown(step, context) {
+  const pdfUtil = new PDFCaptureUtil(context)
+  await pdfUtil.initBrowser(step.connection)
+
+  try {
+    const { accessor, markdownContent, markdownContentAccessor } = step.params
+    const templateInput = access(accessor, context.data)
+    const markdownTemplate = markdownContentAccessor ? access(markdownContentAccessor, context.data) : markdownContent
+
+    const renderedMarkdown = pdfUtil.renderTemplate(markdownTemplate, templateInput)
+    const htmlContent = marked(renderedMarkdown)
+
+    await pdfUtil.processPageAndGeneratePDF(step.params, htmlContent)
+
+    return {
+      data: context.__headless_pdf
+    }
+  } catch (error) {
+    throw error
+  } finally {
+    await pdfUtil.closeBrowser()
+  }
+}
+
+HeadlessPDFCaptureMarkdown.parameterSpec = [
+  ...getCommonParameterSpec(),
+  {
+    type: 'scenario-step-input',
+    name: 'markdownContentAccessor',
+    label: 'markdown-content-accessor'
+  },
+  {
+    type: 'textarea',
+    name: 'markdownContent',
+    label: 'markdown-content'
+  }
+]
+
+HeadlessPDFCaptureMarkdown.help = 'integration/task/headless-pdf-capture-markdown'
+
+TaskRegistry.registerTaskHandler('headless-pdf-capture-markdown', HeadlessPDFCaptureMarkdown)

package/server/engine/task/headless-pdf-capture.ts

@@ -0,0 +1,39 @@
+import { TaskRegistry } from '@things-factory/integration-base'
+import { access } from '@things-factory/utils'
+
+import { PDFCaptureUtil, getCommonParameterSpec } from './pdf-capture-util'
+
+export async function HeadlessPDFCapture(step, context) {
+  const pdfUtil = new PDFCaptureUtil(context)
+  await pdfUtil.initBrowser(step.connection)
+
+  try {
+    const { accessor, htmlContent } = step.params
+    const templateInput = access(accessor, context.data)
+
+    const renderedHtmlContent = pdfUtil.renderTemplate(htmlContent, templateInput)
+
+    await pdfUtil.processPageAndGeneratePDF(step.params, renderedHtmlContent)
+
+    return {
+      data: context.__headless_pdf
+    }
+  } catch (error) {
+    throw error
+  } finally {
+    await pdfUtil.closeBrowser()
+  }
+}
+
+HeadlessPDFCapture.parameterSpec = [
+  ...getCommonParameterSpec(),
+  {
+    type: 'textarea',
+    name: 'htmlContent',
+    label: 'html-content'
+  }
+]
+
+HeadlessPDFCapture.help = 'integration/task/headless-pdf-capture'
+
+TaskRegistry.registerTaskHandler('headless-pdf-capture', HeadlessPDFCapture)