tophant.benjamin

Messages & Enums

message AuthConfig

AuthConfig 用于传递登录配置利用该配置下发（enable = true）的会被用来调用 adam 进行登录如果只是想传递登录结果请使用 AuthResult 注意：当前 AuthConfig 仅用于调试使用，正式环境请始终使用 AuthResult

message AuthConfig {
    bool enable = 1;
    // adam 的服务器地址，默认为 localhost:9998
    string adam_host = 11;
    // 传递给 adam 的登录配置文件，tophant.adam.AuthRecord 的 protojson 序列化格式
    string auth_record = 21;
    // TODO 其他传递给 adam 用于检查登录配置的配置
    double check_interval_seconds = 31;
}

message AuthResult

AuthResult 为登录成功后的结果动态爬虫使用字段：cookies, local_storage, session_storage 静态爬虫使用字段：cookies, additional_headers

message AuthResult {
    bool enable = 1;
    repeated Cookie cookies = 11;
    repeated Pair local_storage = 12;
    repeated Pair session_storage = 13;
    // 动态爬虫不会读取该字段，可使用 RequestConfig 中的 custom_headers 来配置
    repeated Pair additional_headers = 14;
}

message BasicAuth

message BasicAuth {
    bool enable = 1;
    string username = 11;
    string password = 12;
}

message Body

代表请求或响应体，包括大小和内容

message Body {
    // 是否存在 body
    bool exist = 1;
    // body 大小（原始大小）；exist=true + size=0 是可能出现的（发送了 Body 但是完全未能被截获）
    int64 size = 2;
    // body 内容，仅当 exist=true 时存在【如果 Body 过大，data 可能为截断后的内容或完全不存在】
    File data = 11;
    // 可能在某些情况下无法获得 body 的详细信息，这时 exist=true 但是 data=null，而 error 有值
    Mark error = 12;
}

message BrowserAuth

message BrowserAuth {
    bool enable = 1;
    string username = 11;
    string password = 12;
}

message ChromeConfig

ChromeConfig 对应浏览器的启动参数

message ChromeConfig {
    // Chrome 的版本，未来或许我们内置多版本的 Chrome 供自由选用；当前留空即可
    string version = 1;
    // 是否禁用无头模式，留空为否即启用无头模式（不会打开浏览器窗口）
    bool no_headless = 2;
    // 是否启用无痕模式，默认为不启用
    bool incognito_context = 3;
    int64 viewport_width = 4;
    int64 viewport_height = 5;
    // 自定义配置
    CustomChromeConfig custom = 99;
}

message Cookie {
    // 必须
    string name = 1;
    // 必须
    string value = 2;
    // 如果 domain 和 url 均省略，则使用当前页面的 URL
    optional string url = 11;
    optional string domain = 12;
    optional string path = 13;
}

message CustomChromeConfig

CustomChromeConfig 为高级浏览器配置

message CustomChromeConfig {
    map<string,bool> config1 = 1;
    map<string,string> config2 = 2;
}

message CustomScript

message CustomScript {
    // 脚本名称
    string name = 31;
    // 自定义脚本的目标
    MatchTarget target = 1;
    oneof scene {
        bool evaluate_on_new_documents = 11;
        bool evaluate_after_dom_ready = 12;
    }
    // 自定义脚本的内容
    string script = 21;
    // 是否为函数脚本
    bool function = 22;
}

message CustomScriptsConfig

message CustomScriptsConfig {
    bool enable = 1;
    repeated CustomScript scripts = 2;
}

message DebugConfig

message DebugConfig {
    // 开启 debug 模式（注意：该功能仅用于给单独任务开启 debug，如果全局开启了 debug 无法在任务维度关闭）
    bool enable = 101;
    // 是否开启重放（默认为 true）
    optional bool enable_replay = 11;
    // 是否持久化 Target 数据（默认为 true）
    optional bool enable_target_data_persistence = 12;
    // 是否持久化 Result 数据（默认为 true）
    optional bool enable_result_data_persistence = 13;
    // 是否开启 Sentry（默认当 sentry_dsn 不为空时为 true）
    optional bool enable_sentry = 14;
    string sentry_dsn = 2;
    // 请使用 enable_replay
    bool disable_rrweb = 1;
}

message DetectResults

message DetectResults {
    // 用于检测的 URL
    repeated string urls = 1;
    // 检测到的结果
    repeated DetectTechnologyResult technologies = 2;
}

message DetectTechnology

message DetectTechnology {
    string id = 1;
    string name = 2;
    string description = 3;
    string cpe = 4;
    repeated DetectTechnology.Category categories = 5;
    string website = 6;
    string icon = 7;
}

message DetectTechnology.Category

message Category {
    string id = 1;
    string name = 2;
}

message DetectTechnologyResult

message DetectTechnologyResult {
    // 该 technology 的唯一标识
    string id = 1;
    // 置信度，最高 100
    int64 confidence = 2;
    // 版本（版本未知时为空）
    string version = 3;
    // 该 technology 的详细信息，仅在明确指定需要时返回
    optional DetectTechnology detail = 11;
}

message DetectorConfig

message DetectorConfig {
    // enable 指定是否启用 detector
    // detector 有两种使用场景：独立使用 和 作为爬虫的一部分使用
    // 对于独立使用场景，该值始终为 true
    // 对于作为爬虫的一部分使用的场景，该值默认为 true
    bool enable = 1;
    // 页面打开的超时时间，单位为秒，默认 5s
    double open_page_timeout_seconds = 11;
    // 打开页面后额外等待的时间，单位为秒，默认 1s
    double wait_after_open_page_seconds = 12;
    // 仅检测指定的 technology（指定 id 列表），默认（不指定时）检测所有 technology
    repeated string only_detect = 31;
}

message DeviceEmulationConfig

message DeviceEmulationConfig {
    // 是否开启设备模拟
    bool enable = 1;
    // 模拟的屏幕宽度（默认与 viewport_width 相同）
    uint32 emulate_screen_width = 31;
    // 模拟的屏幕高度 （默认与 viewport_height 相同）
    uint32 emulate_screen_height = 32;
    // 模拟的屏幕像素比（默认为 1.0）
    double emulate_screen_device_pixel_ratio = 33;
    // 是否为手机设备（默认为否）
    bool mobile = 51;
    // 是否为触屏设备（默认为否）
    bool touch = 52;
    // 是否旋转 90°（即调转宽和高，用于模拟电脑竖屏/手机横屏，默认为否）
    bool rotate90 = 53;
}

enum DomainPolicy

DomainPolicy 域名跟踪策略（已弃用，请使用 FollowPolicy）

enum DomainPolicy {
    // 同主域（事实上应该叫 SameSLDAndTLD）
    SameTLD = 0;
    // 同域名
    SameDomain = 1;
    // 同域名且子目录（事实上应该叫 SameDomainAndDir）（此时 entrypoints 必须以 / 结尾）
    SameDir = 2;
    // 同二级域，忽略 TLD（SameSLD, IgnoreTLD）
    SameSLD = 3;
    // SameTLD，忽略端口的不同
    SameTLDAllPorts = 11;
    // SameDomain，忽略端口的不同
    SameDomainAllPorts = 12;
    // SameDir，忽略端口的不同（此时 entrypoints 必须以 / 结尾）
    SameDirAllPorts = 13;
    // SameSLD，忽略端口的不同
    SameSLDAllPorts = 14;
}

message ElementHandleConfig

ElementHandleConfig 为处理元素的配置

message ElementHandleConfig {
    bool enable = 1;
    // 忽略新增的元素
    bool ignore_new_elements = 2;
    // 处理的元素列表，默认为 ['a', 'input', 'button', 'form', 'select', 'td', 'area', 'img', 'iframe', 'li', 'span', 'i']
    repeated string elements = 21;
    // 每处理一个元素之后, 尝试新元素次数，默认 0 为自动控制
    uint32 try_new_elements_count = 31;
    // 每次尝试新元素之前的等待时间，单位为秒，默认为 0 为自动控制
    double wait_before_try_new_elements_seconds = 32;
    // 点击任意元素，默认为 false
    bool click_any_element = 33;
    // 等待指定时间之后再处理下一个元素, 该时间会影响对新产生元素的处理, 加大可以多处理新产生的元素，单位为秒，默认为 0 为自动控制
    double wait_before_handle_next_element_seconds = 34;
}

message EventHandleConfig

message EventHandleConfig {
    bool enable = 1;
}

message ExtraAuthConfig

ExtraAuthConfig 额外的登录认证配置，目前仅供 BasicAuth 使用

message ExtraAuthConfig {
    // 用于支持浏览器侧的认证（Basic Auth & Digest Auth）
    BrowserAuth browser_auth = 2;
    // BasicAuth 认证后续会被废弃，建议切换为使用 BrowserAuth
    BasicAuth basic_auth = 1;
}

message File

File 为文件对象的抽象

message File {
    // 文件的实际大小（根据存储后端的不同，可能有截断）
    int64 size = 1;
    // 是否触发了硬限制被截断
    bool truncated = 2;
    // 被截断后的大小（未被截断则等于 size）
    int64 truncated_size = 3;
    // 文件的 MD5 摘要（32 位小写）；对于 truncated=true 的情形该值不准或为空
    string md5 = 9;
    // 具体的存储后端（原则上下面两种必有一个）
    // 
    // 直接存储（仅小文件）
    File_Raw raw = 11;
    // 大文件存储
    StorageFileDesc file = 14;
}

message FileOutputConfig

message FileOutputConfig {
    bool enable = 1;
    // 文件输出路径，为了安全起见，路径必须以 `/data/` 开头
    string path = 11;
}

message File_Raw

File_Raw 为直接明文存储相关内容

message File_Raw {
    // 实际存储的文件大小，可能小于等于 File 的 truncated_size
    int64 size = 1;
    // 实际存储的文件内容
    bytes data = 2;
}

message FollowPolicy

message FollowPolicy {
    FollowPolicy.Policy policy = 1;
    // 是否忽略 featured_url 与即将访问的 url 中的端口（默认不忽略）
    // 适用于 SameTLD SameDomain SameDir SameSLD 策略
    bool ignore_port = 11;
    // 允许将 entry_point 中的 domain 替换为 domain_suffix 中的任意一个（默认不允许）
    // 
    // 为了避免错误理解该功能，所有子项需要以 `.` 开头，否则将会在 validate 阶段报错
    // 
    // 注意：featured_url （或称 featured_entry_point）的 domain_suffix 本身必须满足 alternative_domain_suffix 中的一个
    // 例如，指定了 featured_url = abc.baidu.com.cn 时，alternative_domain_suffix 中必须包括 .baidu.com.cn, .com.cn, .cn 中的其中一个
    // 如果不满足该条件，将会在 validate 阶段报错
    // 
    // 另外，如果 alternative_domain_suffix 中有多个 suffix 满足 featured_url，将采用层级最高的
    // 例如，featured_url = abc.baidu.com.cn 时，指定的 suffix 有 .com.cn 和 .cn，将始终使用 .com.cn 进行域名后缀剔除
    // 
    // 请谨慎使用该配置，该配置会导致 FollowPolicy 的计算时间线性增长
    // 
    // 适用于 SameTLD SameDomain SameDir 策略
    repeated string alternative_domain_suffix = 12;
}

enum FollowPolicy.Policy

enum Policy {
    Invalid = 0;
    // 同主域（事实上为 SameSLDAndTLD，或称 SameTLDPlusOne）
    SameTLD = 1;
    // 同域名
    SameDomain = 2;
    // 同域名且子目录（事实上为 SameDomainAndDir）【此时对应的 featured_url 必须以 / 结尾】
    SameDir = 3;
    // 同二级域，忽略 TLD（SameSLD, ignoreTLD）
    SameSLD = 4;
}

message FormFillConfig

FormFillConfig 全局提示：keyword 为小写代表忽略大小写，keyword 存在大写为大小写敏感

message FormFillConfig {
    // bool enable = 1; // 是否启用表单填充（目前强制启用（以 ElementHandler 控制）
    // 
    // 是否禁用内置的规则
    bool disable_default_rules = 2;
    // 下面的是内置的某些策略
    // 
    // 未知类型填充内容
    repeated string unknown = 20;
    repeated string username = 21;
    repeated string nickname = 22;
    repeated string email = 23;
    repeated string password = 24;
    repeated string phone = 25;
    repeated string color = 26;
    // 自定义根据关键词填充
    repeated FormFillConfig.KeywordConfig custom = 51;
    // 自定义根据类型填充
    repeated FormFillConfig.KeywordConfig custom_for_type = 61;
    // 自定义根据 name 填充
    repeated FormFillConfig.KeywordConfig custom_for_name = 62;
    // 自定义根据 id 填充
    repeated FormFillConfig.KeywordConfig custom_for_id = 63;
}

message FormFillConfig.KeywordConfig

message KeywordConfig {
    // 匹配的关键词
    repeated string keyword = 1;
    // 填充的值，可以是多个，会随机选择一个
    repeated string value = 2;
    // 使用内置策略
    string use = 3;
    // 跳过填充
    bool skip = 4;
}

message KafkaOutputConfig

message KafkaOutputConfig {
    bool enable = 1;
    repeated string addrs = 11;
    string topic = 12;
    KafkaOutputConfig.TlsConfig tls = 13;
}

message KafkaOutputConfig.TlsConfig

message TlsConfig {
    // Enable 代表启用 SSL
    bool enable = 1;
    bytes ca_pem = 2;
    bytes cert_pem = 3;
    bytes key_pem = 4;
    optional string key_password = 5;
}

message LogOutputConfig

message LogOutputConfig {
    bool enable = 1;
}

message Manager

message Manager {
    string host = 1;
}

message Mark

通用标记，用于展示一些信息

message Mark {
    // 标记是否生效，原则上必须为 true
    bool marked = 1;
    // 标记信息，不会为空
    string info = 2;
}

message MatchElement

指定元素的匹配规则

message MatchElement {
    // 满足任一条件即可
    MatchElementConditions conditions = 1;
}

message MatchElementCondition

message MatchElementCondition {
    oneof condition {
        // ElementName
        string name = 1;
        // 内部文本
        string inner_text = 11;
        // 满足多个条件之一即可，要求条件类型必须一致且必须为简单条件；相比于简单的重复 / or 效率更高
        MatchElementConditions repeated_or = 81;
        // 需同时满足多个条件
        MatchElementConditions all = 91;
        // 满足任一条件即可
        MatchElementConditions or = 92;
        // 不可满足该条件
        MatchElementCondition not = 93;
    }
}

message MatchElementConditions

message MatchElementConditions {
    repeated MatchElementCondition conditions = 1;
}

message MatchRequest

指定请求的匹配规则

message MatchRequest {
    // 满足任一条件即可
    MatchRequestConditions conditions = 1;
}

message MatchRequestCondition

message MatchRequestCondition {
    oneof condition {
        // 请求方法
        string method = 1;
        // 域名匹配
        string domain = 11;
        // path 匹配
        string path = 12;
        // path 关键字匹配
        string path_keyword = 21;
        // path 和 query 关键字匹配
        string path_and_query_keyword = 22;
        // url 关键字匹配
        string url_keyword = 23;
        // path 后缀匹配（不含 .)
        string suffix = 31;
        // content-type 关键字匹配
        string content_type_keyword = 32;
        // 满足多个条件之一即可，要求条件类型必须一致且必须为简单条件；相比于简单的重复 / or 效率更高
        MatchRequestConditions repeated_or = 81;
        // 需同时满足多个条件
        MatchRequestConditions all = 91;
        // 满足任一条件即可
        MatchRequestConditions or = 92;
        // 不可满足该条件
        MatchRequestCondition not = 93;
    }
}

message MatchRequestConditions

message MatchRequestConditions {
    repeated MatchRequestCondition conditions = 1;
}

message MatchTarget

指定 Target 的匹配规则

message MatchTarget {
    // 满足任一条件即可
    MatchTargetConditions conditions = 1;
}

message MatchTargetCondition

message MatchTargetCondition {
    oneof condition {
        // 利用对应的 canonical url 进行匹配
        string url = 1;
        // 精确匹配 URL
        string url_precise = 2;
        string domain = 11;
        string path = 12;
        // 源，支持通配符，* 代表匹配全部，Entrypoint* 代表匹配入口 URL
        string source_detail = 22;
        // 需同时满足多个条件
        MatchTargetConditions all = 91;
        // 满足任一条件即可
        MatchTargetConditions or = 92;
        // 不可满足该条件
        MatchTargetCondition not = 93;
    }
}

message MatchTargetConditions

message MatchTargetConditions {
    repeated MatchTargetCondition conditions = 1;
}

message NatsOutputConfig

message NatsOutputConfig {
    bool enable = 1;
    string dsn = 11;
    string subject = 12;
}

message NetworkConfig

NetworkConfig 为核心网络层的配置

message NetworkConfig {
    // 上游代理
    string upstream_proxy = 21;
}

message Note

message Note {
    google.protobuf.Timestamp time = 1;
    // namespace，应当为大写字母、下划线分隔的格式
    string namespace = 2;
    string message = 3;
    map<string,string> fields = 9;
}

message OSSConfig

message OSSConfig {
    string endpoint = 1;
    bool use_ssl = 2;
    string access_key_id = 11;
    string access_key_secret = 12;
    string bucket = 21;
}

message OutputConfig

message OutputConfig {
    FileOutputConfig file = 1;
    KafkaOutputConfig kafka = 2;
    NatsOutputConfig nats = 3;
    // just for debug
    LogOutputConfig log = 99;
}

message Pair

一个 name-value 对

message Pair {
    string name = 1;
    string value = 2;
}

message Redirect

Redirect 代表着重定向信息，当 Target 或 Result 的请求中出现重定向时会产生该对象

message Redirect {
    // 重定向使用的 status code
    int32 status_code = 1;
    // 重定向目标
    string next = 2;
    // 重定向目标的 canonical URL（根据该 Redirect 属于 Target 与 Result 的不同，标准化算法亦不同）
    string next_canonical = 3;
    // 重定向响应的响应头【可能没有】
    repeated Pair headers = 11;
    // 重定向响应的 body【可能没有】
    Body body = 12;
}

message RemoveElement

message RemoveElement {
    // 名称，标识该元素
    string name = 1;
    // 目标
    MatchTarget target = 11;
    // CSS 选择器
    repeated string css_selector = 21;
    // 打开页面后【额外】等待的时间，单位为秒，0 为不等待
    int32 wait_after_open_seconds = 31;
    // 等待元素出现的时间，单位为秒，0 为不等待，负数为无限等待（慎用，如果元素不存在会一直等待到页面超时）
    int32 wait_for_element_seconds = 32;
}

message RemoveElementsConfig

message RemoveElementsConfig {
    bool enable = 1;
    repeated RemoveElement remove_elements = 2;
}

message Request

message Request {
    // 请求的原始 URL
    string url = 1;
    // 请求方法，一定为大写，例如 GET / POST / PUT / DELETE / PATCH / HEAD / OPTIONS 等
    string method = 2;
    // 请求头（Header Name 已经标准化过，全为小写，但不可依赖该标准化行为）
    repeated Pair headers = 3;
    Body body = 4;
}

message RequestBlockConfig

message RequestBlockConfig {
    // 禁止的方法列表，必须为大写字母，默认为空（DELETE 方法不使用该字段控制，请使用 allow_delete_method）
    repeated string block_methods = 1;
    // 是否允许 DELETE 请求，默认为不允许
    bool allow_delete_method = 2;
    // 是否允许静态文件，默认为不允许（会返回 ClientBlock）
    bool allow_static_files = 11;
    // 关闭自带的禁止规则
    bool disable_default_block_rules = 31;
    // 额外的自定义禁止规则
    MatchRequest block_rules = 32;
}

message RequestConfig

RequestConfig 为发送请求时的配置

message RequestConfig {
    string user_agent = 1;
    string accept_language = 4;
    // TODO not work now
    string referer = 2;
    // 指定自定义 headers
    // 该参数会适用于页面上的所有请求，在几乎任何情况下均不建议使用
    // 为了防止异常行为，如果在这里指定如下 header 会报错：
    // 	"connection", "content-length", "cookie", "host", "user-agent"
    repeated Pair custom_headers = 9;
    repeated Pair cookies = 3;
    repeated Pair local_storage = 11;
    repeated Pair session_storage = 12;
    // 超时时间配置
    // 
    // 单页面爬取的最大时间，单位为秒，默认 0 为自动控制
    double single_page_timeout_seconds = 21;
    // 页面打开的超时时间，单位为秒，默认 0 为自动控制
    double open_page_timeout_seconds = 22;
    // 操作进程时间配置
    // 
    // 在已经确认页面加载完成到进行页面处理的等待时间，单位为秒，默认 0 为自动控制
    double wait_after_open_page_seconds = 31;
    // 在处理完所有页面到关闭网页的处理的等待时间，单位为秒，默认 0 为自动控制
    double wait_before_close_page_seconds = 32;
    // 两个处理步骤之间的等待时间，单位为秒，默认 0 为自动控制
    double wait_between_handle_steps_seconds = 33;
    // 位置模拟配置
    // 
    // 是否开启位置模拟
    bool enable_emulate_location = 51;
    // 模拟纬度
    double location_latitude = 52;
    // 模拟经度
    double location_longitude = 53;
}

enum ResourceType

enum ResourceType {
    Invalid = 0;
    XHR = 1;
    Fetch = 2;
    Stylesheet = 11;
    Image = 12;
    Media = 13;
    Font = 14;
    Script = 15;
    TextTrack = 16;
    EventSource = 21;
    WebSocket = 22;
    Manifest = 23;
    SignedExchange = 24;
    Ping = 25;
    CSPViolationReport = 26;
    Preflight = 27;
    Document = 98;
    Other = 99;
    Unknown = 100;
}

message Response

message Response {
    // 相应返回值
    int32 status_code = 1;
    // 响应头（Header Name 已经标准化过，全为小写，但不可依赖该标准化行为）
    repeated Pair headers = 2;
    Body body = 3;
}

message Result

message Result {
    // 结果的唯一 ID
    string id = 1;
    // 结果所属的 target 信息
    TargetId target = 2;
    // 结果的 URL，理论上与 Request 中的 url 相同
    string url = 3;
    // 结果的 canonical URL，暂时没啥用，只是算出来了
    string canonical_url = 4;
    ResourceType resource_type = 21;
    Request request = 22;
    Response response = 23;
    repeated Redirect redirects = 24;
    // 是否为 Target Document
    bool is_target_document = 25;
    // 是否为外链
    bool is_external = 26;
    // 请求失败时标记，info 为失败原因
    Mark fail = 31;
    // 是否被规则阻止
    bool blocked = 32;
    Result.Timing timing = 41;
}

message Result.Timing

message Timing {
    // 请求触发的时间
    google.protobuf.Timestamp start_time = 1;
    // 请求结束的时间
    google.protobuf.Timestamp end_time = 2;
}

message SchedulerConfig

message SchedulerConfig {
    // 覆盖使用的 Docker 镜像
    string override_docker_image = 1;
}

enum ScreenshotPolicy

enum ScreenshotPolicy {
    // 禁用（不截图）
    Disable = 0;
    // 每个网页都截图
    Always = 1;
}

message Site

message Site {
    string url = 1;
    FollowPolicy policy = 2;
}

message StorageConfig

StorageConfig 为用于进行存储的配置

message StorageConfig {
    // 最大保存多大的资源 body, 单位为 Bytes，默认限制为 10MB
    int64 collect_body_size_limit_bytes = 1;
    // 对于 Documents/XHR/Fetch 的存储大小分界线（小于等于该值存储为 Raw，否则为 Local/OSS）
    int64 collect_body_size_dividing_normal_bytes = 11;
    // 对于静态资源（Stylesheet/Image/Media/Font/Script/TextTrack）的存储大小分界线（小于等于该值存储为 Raw，否则为 Local/OSS）
    int64 collect_body_size_dividing_static_bytes = 12;
    // 对于其他资源的存储大小分界线（小于等于该值存储为 Raw，否则为 Local/OSS）
    int64 collect_body_size_dividing_other_bytes = 13;
    // Raw 最大保存多大的资源 body, 单位为 Bytes，超出该值会被截断，默认限制为 10MB
    int64 raw_body_size_limit_bytes = 21;
    // Local 最大保存多大的资源 body, 单位为 Bytes，超出该值会被截断，默认为不限制
    int64 local_body_size_limit_bytes = 31;
    // OSS 最大保存多大的资源 body, 单位为 Bytes，超出该值会被截断，默认为不限制
    int64 oss_body_size_limit_bytes = 41;
    // RRWeb 数据的存储策略
    StoragePolicy rrweb_storage_policy = 71;
    // 截图数据的存储策略
    StoragePolicy screenshot_storage_policy = 72;
    // OSS 配置
    OSSConfig oss = 91;
}

message StorageFileDesc

message StorageFileDesc {
    StoragePolicy position = 1;
    string key = 2;
    // 文件大小
    optional int64 size = 11;
    // 仅当 StoragePolicy = OSS 时存在
    // TODO 这个字段实际上不应该存在，仅为临时解决方案，未来可能会移除
    string oss_bucket = 21;
}

enum StoragePolicy

enum StoragePolicy {
    Default = 0;
    Local = 1;
    OSS = 2;
}

message Target

message Target {
    string id = 1;
    // Url 为访问浏览器时输入的 url
    string url = 2;
    // CanonicalUrl 为标准化以后用于去重等的 url
    string canonical_url = 3;
    // target 的来源信息
    TargetSource source = 4;
    // target 的来源信息，相比于 source 更详细（但可能为空）
    string source_detail = 6;
    // Target 所属任务
    TaskId task = 5;
    // 首次出现时父目标的 ID；如果出现在多个父 Target 中也只会包含一个（聚合由下游根据 TargetFoundEvent 进行）
    string parent_target_id = 12;
    // Target 的层级，从 1 开始，根目标为 0
    int64 level = 13;
    // 继承的目标 ID，如果为空则表示没有继承
    string inherit_target_id = 14;
    // 爬取状态，有 pending, running, done, bypass 几种
    Target.Status status = 21;
    // 错误原因（空为无错误，仅当状态为 Done 时有值）
    string error = 32;
    // 加载网页时产生的 Document 请求
    Request request = 41;
    // 加载网页时产生的 Document 响应 + 网页渲染后的 Body 内容
    TargetResponse response = 42;
    repeated Redirect redirects = 43;
    // 网页截图（可能不存在，具体取决于 ScreenshotPolicy）
    StorageFileDesc screenshot = 46;
    Target.Timing timing = 44;
    // 附加信息
    repeated Note notes = 45;
}

enum Target.Status

enum Status {
    Pending = 0;
    Running = 1;
    Done = 2;
    // 爬取 target url 时存在重定向
    Redirected = 7;
    // 爬取过程中丢弃的目标，通常为爬取过程中发现为无效目标的情况
    Discard = 8;
    // 自始不爬取，通常由过滤器过滤
    Bypass = 9;
}

message Target.Timing

message Timing {
    // Target 发现时间
    google.protobuf.Timestamp found_at = 1;
    // Target 开始爬取时间
    google.protobuf.Timestamp start_at = 2;
    // Target 爬取后页面加载完成时间
    google.protobuf.Timestamp load_at = 4;
    // Target 结束爬取时间
    google.protobuf.Timestamp end_at = 3;
}

message TargetId

Target 的标志性

message TargetId {
    // Target 所属的 task
    TaskId task = 1;
    // Target 的 ID
    string id = 2;
}

message TargetResponse

message TargetResponse {
    Response response = 1;
    // 渲染后的 body
    Body rendered_body = 2;
}

enum TargetSource

Target 的来源

enum TargetSource {
    // 任务指定的入口
    Endpoint = 0;
    // 运行时额外指定的入口
    Extra = 1;
    // 从 sitemap.xml 拓展的页面
    Sitemap = 11;
    // 从 robots.txt 拓展的页面
    Robots = 12;
    // 目录遍历
    Directory = 13;
    StaticDOM = 31;
    StaticHistory = 32;
    StaticFile = 33;
    // 动态爬虫爬取时发现的页面
    Dynamic = 41;
    // 动态爬虫路由钩子发现的页面
    DynamicRouterHook = 42;
}

message TargetStatistic

TargetStatistic 描述了一个任务的 Targets 统计信息提示：在开发者工具中，展示的信息为 (done + discard) / (pending + running + done + discard)

message TargetStatistic {
    // 页面总数
    int64 total = 1;
    // 等待执行的任务数，Status = Pending
    int64 pending = 10;
    // 正在执行的任务数，Status = Running
    int64 running = 11;
    // 已经执行完成的任务数，Status = Done
    int64 done = 12;
    // 丢弃的任务数，Status = Redirected + Discard
    int64 discard = 18;
    // 完全不爬取的任务数，Status = Bypass
    int64 bypass = 19;
}

message Task

message Task {
    string id = 1;
    // job_id + iterate 是唯一的
    string job_id = 2;
    // 迭代数量
    int64 iterate = 3;
    // 任务名称
    string job_name = 6;
    // 时间ID，非唯一
    string tid = 4;
    // 任务的状态
    Task.Status status = 5;
    // 任务创建时间
    google.protobuf.Timestamp created_at = 21;
    // 任务的最后修改时间
    google.protobuf.Timestamp updated_at = 22;
    // 任务开始时间
    google.protobuf.Timestamp start_at = 23;
    // 任务结束时间
    google.protobuf.Timestamp stop_at = 24;
    // 任务心跳时间
    google.protobuf.Timestamp tick = 31;
    // 是否失败、失败原因
    Mark error = 33;
    // 附加信息
    repeated Note notes = 34;
    // Task 所属的 Manager 信息
    // 仅供内部使用，现已从 entity.Task 中移除，如需使用请访问 xentity.Task
    Manager manager = 32;
}

enum Task.Status

enum Status {
    // 等待运行
    Pending = 0;
    // 正在运行中
    Running = 1;
    // 运行完成（可能是执行完了、超时、被终止等，请查看 stop_reason 字段）
    Done = 2;
    // 停止中
    Stopping = 21;
    // 任务失败（仅预检才会产生任务失败）
    Fail = 22;
}

message TaskConfig

message TaskConfig {
    // 给定的任务 ID
    string job_id = 1;
    // 给定的任务名称
    string job_name = 2;
    // 爬虫初始 URL 列表，至少有一个，DomainPolicy 将基于这些 URL 中的第一个计算；该字段指定的目标一定会被爬取，无论是否满足设定的 domain_policy
    repeated string entry_points = 3;
    // 额外的初始 URL 列表，这些 URL 会被追加至 entry_points 中；主要用于 customize 指定，实际效果与追加在 entrypoints 中完全一样
    repeated string extra_entry_points = 7;
    // 可能的初始 URL 列表，历史遗留字段，目前效果与 extra_entry_points 一致
    repeated string potential_entry_points = 8;
    // 特征 Entrypoint，默认为 EntryPoints 的第一个，DomainPolicy 会基于此计算；该字段指定可以不在 entry_points 中，此时该字段所指定的目标也不会被爬取
    string featured_entry_point = 5;
    // 跟踪策略
    FollowPolicy follow_policy = 10;
    // 额外指定 sites
    // 通常情况下，使用 featured_entry_point 配合 domain_policy 可以自动构建出默认 Site
    // 对于高级情形，可以使用 sites 指定更多的 Site 信息 —— 满足任一爬取规则均会爬取
    // 
    // 利用 sites 所指定的 site 和利用 featured_entry_point + domain_policy 所自动生成的 site 会被合并
    repeated Site sites = 9;
    // 并发配置
    int64 browser_concurrency = 11;
    int64 tab_concurrency = 12;
    // 外部数据源
    bool analyse_robots_txt = 21;
    bool analyse_sitemap = 22;
    // 爬取范围限制
    // 
    // 最大爬取层级，默认为 999【仅用于防止死循环】
    int64 max_depth = 31;
    // 结果情况限制
    // 
    // 最大的爬取目标数（默认 0 不限制）（非精准限制）
    int64 max_target = 41;
    // 最大的记录结果数（默认 0 不限制）（非精准限制）
    int64 max_result = 42;
    // 爬取时间限制
    // 
    // 最大的爬取时间（单位为秒，默认 0 不限制）（非精准限制）
    int64 max_time_seconds = 43;
    // 浏览器配置
    ChromeConfig chrome = 51;
    // 设备模拟配置
    DeviceEmulationConfig device_emulation_config = 50;
    // 网络配置
    NetworkConfig network_config = 56;
    // 爬取过程配置
    RequestConfig request_config = 52;
    StorageConfig storage_config = 53;
    // 认证配置
    AuthResult auth_result = 55;
    // 额外认证配置
    ExtraAuthConfig extra_auth_config = 57;
    // 截图策略
    ScreenshotPolicy screenshot_policy = 58;
    // 调试配置
    DebugConfig debug_config = 59;
    // 调度器配置
    SchedulerConfig scheduler_config = 60;
    // 元素处理配置
    ElementHandleConfig element_handle_config = 61;
    // 自定义事件处理
    EventHandleConfig event_handle_config = 62;
    // 自定义表单填充
    FormFillConfig form_fill_config = 63;
    // TODO 自定义忽略规则
    // 
    // 禁止请求配置
    RequestBlockConfig request_block_config = 66;
    // 自定义脚本行为
    CustomScriptsConfig custom_scripts_config = 71;
    // 移除指定元素
    RemoveElementsConfig remove_elements_config = 72;
    // 输出配置，控制事件广播位置，至少有一个，否则会报错
    OutputConfig output_config = 91;
    // protojson 编码的自定义配置（UseProtoName=true & UseEnumNumber=false）
    string customize = 101;
    repeated string flags = 99;
    // 认证配置（请勿主动使用，而是将认证信息写入 auth_result）
    AuthConfig auth_config = 54;
    // 跟踪策略（已弃用，请使用 follow_policy）
    DomainPolicy domain_policy = 6;
}

message TaskId

TaskId 为这个 Task 的唯一标识

message TaskId {
    string id = 1;
    string job_id = 2;
    int64 iterate = 3;
}

message TaskStatus

TaskStatus 标记着一个任务的状态

message TaskStatus {
    // 任务是否仍在运行
    bool is_running = 11;
    // 任务是否不存在
    bool is_not_exist = 21;
    // 任务是否处于等待状态
    bool is_pending = 22;
    // 任务是否还在停止中
    bool is_stopping = 23;
    // 24 - 任务是否正常结束 TODO
    // 25 - 任务是否超时结束 TODO （目前没有超时）
    // 
    // 任务是否被手动停止 TODO 当前尚未记录是否为手动停止
    bool is_manually_stopped = 26;
    // 任务是否心跳超时
    bool is_disconnect = 27;
}

message UpdateTaskConfig

message UpdateTaskConfig {
    oneof base {
        // 新的任务配置（job_id 和 job_name 会被忽略）
        TaskConfig config = 1;
    }
    // 额外 URL 列表，如果已经爬取过会重新爬取（爬取到已经爬取过的目标则依然会被忽略）
    repeated string extra_urls = 11;
}

Messages & Enums​

message AuthConfig​

message AuthResult​

message BasicAuth​

message Body​

message BrowserAuth​

message ChromeConfig​

message Cookie​

message CustomChromeConfig​

message CustomScript​

message CustomScriptsConfig​

message DebugConfig​

message DetectResults​

message DetectTechnology​

message DetectTechnology.Category​

message DetectTechnologyResult​

message DetectorConfig​

message DeviceEmulationConfig​

enum DomainPolicy​

message ElementHandleConfig​

message EventHandleConfig​

message ExtraAuthConfig​

message File​

message FileOutputConfig​

message File_Raw​

message FollowPolicy​

enum FollowPolicy.Policy​

message FormFillConfig​

message FormFillConfig.KeywordConfig​

message KafkaOutputConfig​

message KafkaOutputConfig.TlsConfig​

message LogOutputConfig​

message Manager​

message Mark​

message MatchElement​

message MatchElementCondition​

message MatchElementConditions​

message MatchRequest​

message MatchRequestCondition​

message MatchRequestConditions​

message MatchTarget​

message MatchTargetCondition​

message MatchTargetConditions​

message NatsOutputConfig​

message NetworkConfig​

message Note​

message OSSConfig​

message OutputConfig​

message Pair​

message Redirect​

message RemoveElement​

message RemoveElementsConfig​

message Request​

message RequestBlockConfig​

message RequestConfig​

enum ResourceType​

message Response​

message Result​

message Result.Timing​

message SchedulerConfig​

enum ScreenshotPolicy​

message Site​

message StorageConfig​

message StorageFileDesc​

enum StoragePolicy​

message Target​

enum Target.Status​

message Target.Timing​

message TargetId​

message TargetResponse​

enum TargetSource​

message TargetStatistic​

message Task​

enum Task.Status​

message TaskConfig​

message TaskId​

message TaskStatus​

message UpdateTaskConfig​