crawlrs 0.2.0

crawlrs - Enterprise-grade web scraping and crawling platform built with Rust
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
// Copyright (c) 2025-2026 Kirky.X🌠
// SPDX-License-Identifier: Apache-2.0

/// Service type enumeration.
enum ServiceType {
    Api,
    Worker,
    Bootstrap,
    Migrate,
}

/// Parse service type from an optional argument string.
///
/// Pure function extracted from `from_args` for testability.
/// - `Some("api")` or `None` → `Ok(ServiceType::Api)`
/// - `Some("worker")` → `Ok(ServiceType::Worker)`
/// - `Some("bootstrap")` → `Ok(ServiceType::Bootstrap)`
/// - `Some("migrate")` → `Ok(ServiceType::Migrate)`
/// - Other values → `Err` with descriptive message
fn parse_service_type(arg: Option<&str>) -> Result<ServiceType, String> {
    let service_type = arg.unwrap_or("api");
    match service_type {
        "api" => Ok(ServiceType::Api),
        "worker" => Ok(ServiceType::Worker),
        "bootstrap" => Ok(ServiceType::Bootstrap),
        "migrate" => Ok(ServiceType::Migrate),
        other => Err(format!(
            "Invalid service type: '{}'. Use 'api', 'worker', 'bootstrap', or 'migrate'.",
            other
        )),
    }
}

impl ServiceType {
    /// Parse service type from command line arguments.
    /// Uses safe `args_os` + explicit UTF-8 handling instead of `env::args`,
    /// which panics on non-UTF-8 OS arguments without a user-facing error.
    fn from_args() -> Self {
        use log::error;
        use std::{env, process};
        let args: Vec<String> = env::args_os()
            .enumerate()
            .map(|(i, os)| match os.into_string() {
                Ok(s) => s,
                Err(utf8_err) => {
                    eprintln!(
                        "crawlrs: argument {} contains invalid UTF-8: {:?}",
                        i, utf8_err
                    );
                    process::exit(2);
                }
            })
            .collect();
        let arg = args.get(1).map(String::as_str);
        match parse_service_type(arg) {
            Ok(st) => st,
            Err(msg) => {
                error!("{}", msg);
                process::exit(1);
            }
        }
    }
}

/// api 停机信号:SIGTERM/SIGINT(Unix)或 Ctrl+C(非 Unix 降级)。
/// 与 worker 模式的 `listen_unix_signals` 语义对齐,但不绑定 coordinator
///(api 排空经 axum graceful shutdown 承载)。
async fn shutdown_signal() {
    #[cfg(unix)]
    {
        use tokio::signal::unix::{signal, SignalKind};
        let mut sigterm = signal(SignalKind::terminate()).expect("install SIGTERM handler");
        let mut sigint = signal(SignalKind::interrupt()).expect("install SIGINT handler");
        tokio::select! {
            _ = sigterm.recv() => {
                log::info!("SIGTERM received, draining API server");
            }
            _ = sigint.recv() => {
                log::info!("SIGINT received, draining API server");
            }
        }
    }
    #[cfg(not(unix))]
    {
        tokio::signal::ctrl_c()
            .await
            .expect("install Ctrl+C handler");
        log::info!("Ctrl+C received, draining API server");
    }
}

mod app {
    use super::ServiceType;
    use crawlrs::bootstrap::routes::build_api_app_with_state;
    use crawlrs::bootstrap::workers::spawn_common_workers;
    use crawlrs::di::modules::{
        CacheModule, DatabaseModule, EngineModule, HttpModule, IdModule, InfrastructureModule,
        RepositoryModule, ServiceModule, SettingsModule,
    };
    use crawlrs::di::{CrawlRsState, CrawlRsStateExt};
    use crawlrs::workers::manager::{WorkerManager, WorkerManagerConfig, WorkerManagerDeps};
    use crawlrs::workers::shutdown::ShutdownCoordinator;
    use std::env;
    use std::sync::Arc;
    use tokio::net::TcpListener;
    use trait_kit::AsyncKit;

    /// Start the API service.
    async fn start_api_service(
        app_state: &CrawlRsState,
        settings: Arc<crawlrs::config::settings::Settings>,
    ) -> anyhow::Result<()> {
        log::info!("Starting API service...");

        // Auto-bootstrap: create initial admin API key if env var is set.
        // This must run in the same process as the API server so that garrison's
        // in-memory oxcache retains the key for auth verification.
        if env::var("CRAWLRS_BOOTSTRAP_ADMIN")
            .map(|v| v.eq_ignore_ascii_case("true") || v.eq_ignore_ascii_case("1"))
            .unwrap_or(false)
        {
            log::info!("CRAWLRS_BOOTSTRAP_ADMIN=true, running auto-bootstrap...");
            run_bootstrap(app_state, &settings).await?;
        }

        // 启动通用 worker(webhook / backlog / expiration)
        let _common_worker_handles = spawn_common_workers(app_state, &settings).await;

        let app = build_api_app_with_state(app_state, settings.clone());

        let addr = format!("{}:{}", settings.server.host, settings.server.port);
        let listener = TcpListener::bind(&addr).await?;
        log::info!("Server listening on {}", addr);

        // 停机排空:信号触发后先完成 fluxweir 网关 flush(pre-aggregator/
        // 配额账本落库),再放行进程退出(fluxweir-llm-gateway D2 顺序钉死)
        let gateway_for_shutdown = app_state.fluxweir_gateway();
        axum::serve(
            listener,
            app.into_make_service_with_connect_info::<std::net::SocketAddr>(),
        )
        .with_graceful_shutdown(async move {
            crate::shutdown_signal().await;
            gateway_for_shutdown.shutdown().await;
        })
        .await?;

        Ok(())
    }

    /// Start the worker service.
    async fn start_worker_service(
        app_state: &CrawlRsState,
        settings: Arc<crawlrs::config::settings::Settings>,
        http_client: Arc<reqwest::Client>,
    ) -> anyhow::Result<()> {
        log::info!("Starting Worker service...");

        // 优雅退出编排
        //
        // 创建共享 ShutdownCoordinator,spawn 信号监听任务(SIGTERM/SIGINT →
        // trigger),替换裸 `tokio::signal::ctrl_c.await`:
        // - `worker_manager.wait_for_shutdown` 内部经 coordinator 阻塞等待信号,
        // 随后给进行中任务 ≤ graceful_period 的宽限期完成,再终止剩余句柄;
        // - 宽限期结束后 `rollback_pending_tasks` 把已锁定未完成任务回滚为 Pending。
        let coordinator = Arc::new(ShutdownCoordinator::new(std::time::Duration::from_secs(
            settings.workers.graceful_shutdown_seconds,
        )));
        spawn_shutdown_signal_listener(coordinator.clone());

        // 启动通用 worker(webhook / backlog / expiration)
        let _common_worker_handles = spawn_common_workers(app_state, &settings).await;

        // Create worker manager with dependencies (使用 DI 注入的服务)
        let deps = build_worker_manager_deps(app_state, http_client, coordinator.clone());

        let config = WorkerManagerConfig {
            settings: settings.clone(),
            default_concurrency_limit: settings.concurrency.default_team_limit as usize,
        };

        let mut worker_manager = WorkerManager::new(deps, config);

        let worker_count = settings.workers.count.resolve();
        log::info!("Starting {} worker(s)", worker_count);
        worker_manager.start_workers(worker_count).await;

        // 记录本进程 worker 认领身份,供停机回滚限定范围(不误回滚其他副本)
        let worker_ids = worker_manager.worker_ids();

        // Keep the main thread alive until shutdown signal
        worker_manager.wait_for_shutdown().await;
        log::info!("Shutting down worker service...");

        // 分阶段停机(吸收自研 trait-kit `shutdown` kit):
        // in-flight 回滚挂入 DrainQueue 阶段,由协调器按阶段超时执行;
        // 后续新增停机清理(连接池关闭、日志落盘)注册到对应阶段即可,无需改编排。
        register_worker_shutdown_hooks(&coordinator, app_state, &settings, worker_ids);
        coordinator.run_phased_shutdown().await;

        Ok(())
    }

    /// Spawn the signal listener that triggers the shared shutdown coordinator.
    fn spawn_shutdown_signal_listener(coordinator: Arc<ShutdownCoordinator>) {
        tokio::spawn(async move {
            if let Err(e) = crawlrs::workers::shutdown::listen_unix_signals(coordinator).await {
                log::error!("Failed to listen for shutdown signals: {}", e);
            }
        });
    }

    /// Build worker-manager dependencies from the shared application state.
    fn build_worker_manager_deps(
        app_state: &CrawlRsState,
        http_client: Arc<reqwest::Client>,
        coordinator: Arc<ShutdownCoordinator>,
    ) -> WorkerManagerDeps {
        WorkerManagerDeps {
            queue: app_state.task_queue(),
            repository: app_state.task_repo(),
            result_repository: app_state.result_repo(),
            crawl_repository: app_state.crawl_repo(),
            webhook_service: app_state.webhook_service(),
            credits_repository: app_state.credits_repo(),
            engine_client: app_state.engine_client(),
            create_scrape_use_case: app_state.create_scrape_use_case(),
            team_semaphore: app_state.team_semaphore.clone(),
            request_coalescer: app_state.request_coalescer.clone(),
            robots_checker: app_state.robots_checker.clone(),
            http_client,
            extraction_service: app_state.extraction_service(),
            content_extractor: app_state.content_extractor(),
            cache_service: app_state.cache_service(),
            shutdown_coordinator: coordinator,
            searxng_instances: app_state.searxng_instances(),
        }
    }

    /// Register the phased shutdown hooks for the worker service.
    fn register_worker_shutdown_hooks(
        coordinator: &ShutdownCoordinator,
        app_state: &CrawlRsState,
        settings: &crawlrs::config::settings::Settings,
        worker_ids: Vec<crawlrs::domain::id::Id>,
    ) {
        let repo_for_rollback = app_state.task_repo();
        let rollback_graceful =
            std::time::Duration::from_secs(settings.workers.graceful_shutdown_seconds);
        coordinator.register_shutdown_hook(
            crawlrs::workers::shutdown::ShutdownPhase::DrainQueue,
            move || {
                Box::pin(async move {
                    crawlrs::workers::shutdown::rollback_pending_tasks(
                        &repo_for_rollback,
                        rollback_graceful,
                        &worker_ids,
                    )
                    .await;
                })
            },
        );
        // fluxweir 网关 flush:CloseConnections 阶段执行(flush 完成才放行
        // 连接关闭;fluxweir-llm-gateway D2 顺序钉死)
        let gateway_for_worker = app_state.fluxweir_gateway();
        coordinator.register_shutdown_hook(
            crawlrs::workers::shutdown::ShutdownPhase::CloseConnections,
            move || {
                Box::pin(async move {
                    gateway_for_worker.shutdown().await;
                })
            },
        );
    }

    /// Bootstrap: create initial team and admin API key for first-time deployment.
    async fn run_bootstrap(
        app_state: &CrawlRsState,
        _settings: &Arc<crawlrs::config::settings::Settings>,
    ) -> anyhow::Result<()> {
        use crawlrs::common::constants::default_identity::DEFAULT_TEAM_ID;

        let pool = app_state.db_pool();
        let session = pool
            .get_session("admin")
            .await
            .map_err(|e| anyhow::anyhow!("db session: {}", e))?;
        let conn = session
            .connection()
            .map_err(|e| anyhow::anyhow!("db conn: {}", e))?;

        // 1. Ensure default team exists
        let team_id = DEFAULT_TEAM_ID;
        ensure_default_team(conn, team_id).await?;

        // 2. Create admin API key via garrison
        #[cfg(feature = "auth")]
        {
            create_bootstrap_admin_key(conn, team_id).await?;
        }

        #[cfg(not(feature = "auth"))]
        {
            println!("Auth feature is not enabled in this build.");
            println!("Rebuild with default features to enable authentication.");
        }

        Ok(())
    }

    /// Ensure default team exists(自 [`ServiceType::run_bootstrap`] 提取)。
    async fn ensure_default_team(
        conn: &dbnexus::sea_orm::DatabaseConnection,
        team_id: crawlrs::domain::id::Id,
    ) -> anyhow::Result<()> {
        use crawlrs::infrastructure::database::entities::team;
        use dbnexus::sea_orm::{EntityTrait, Set};
        let existing = team::Entity::find_by_id(team_id)
            .one(conn)
            .await
            .map_err(|e| anyhow::anyhow!("find team: {}", e))?;
        if existing.is_none() {
            let now = chrono::Utc::now();
            let model = team::ActiveModel {
                id: Set(team_id.into()),
                name: Set("default-team".to_string()),
                allowed_countries: Set(None),
                blocked_countries: Set(None),
                ip_whitelist: Set(None),
                domain_blacklist: Set(None),
                enable_geo_restrictions: Set(false),
                created_at: Set(now.into()),
                updated_at: Set(now.into()),
            };
            team::Entity::insert(model)
                .exec(conn)
                .await
                .map_err(|e| anyhow::anyhow!("insert team: {}", e))?;
            println!("Created team: {}", team_id);
        } else {
            println!("Team already exists: {}", team_id);
        }
        Ok(())
    }

    /// Create admin API key via garrison(自 [`ServiceType::run_bootstrap`] 提取)。
    #[cfg(feature = "auth")]
    async fn create_bootstrap_admin_key(
        conn: &dbnexus::sea_orm::DatabaseConnection,
        team_id: crawlrs::domain::id::Id,
    ) -> anyhow::Result<()> {
        let (api_key_id, plaintext_key) = provision_admin_key_row(conn, team_id).await?;
        print_bootstrap_admin_key(api_key_id, team_id, &plaintext_key);
        Ok(())
    }

    /// 经 garrison 生成 admin key 并写入 `api_keys` 映射行。
    #[cfg(feature = "auth")]
    async fn provision_admin_key_row(
        conn: &dbnexus::sea_orm::DatabaseConnection,
        team_id: crawlrs::domain::id::Id,
    ) -> anyhow::Result<(crawlrs::domain::id::Id, String)> {
        use crawlrs::infrastructure::database::entities::api_key;
        use dbnexus::sea_orm::{EntityTrait, Set};
        use garrison::protocol::apikey::ApiKeyHandler;

        let dao = crawlrs::infrastructure::auth::garrison_dao::get_garrison_dao()
            .ok_or_else(|| anyhow::anyhow!("garrison DAO not initialized"))?;
        let handler = ApiKeyHandler::new(dao);
        let api_key_id = crawlrs::domain::id::Id::generate();
        let login_id = api_key_id.to_string();
        let scopes = vec![
            "crawlrs:read".to_string(),
            "crawlrs:write".to_string(),
            "crawlrs:admin".to_string(),
        ];
        let expires_in_secs: i64 = 365 * 24 * 3600;
        let plaintext_key = handler
            .generate_with_namespace(login_id, "crawlrs", scopes, expires_in_secs)
            .await
            .map_err(|e| anyhow::anyhow!("garrison generate key: {}", e))?;

        // Extract key_id from "key_id.key_secret" format
        let garrison_key_id = match plaintext_key.split_once('.') {
            Some((k_id, _)) => k_id.to_string(),
            None => return Err(anyhow::anyhow!("garrison returned malformed key")),
        };

        // 3. Insert api_keys mapping
        let now_ts = chrono::Utc::now();
        let key_model = api_key::ActiveModel {
            id: Set(api_key_id.into()),
            team_id: Set(team_id.into()),
            key: Set(garrison_key_id),
            created_at: Set(now_ts.into()),
            updated_at: Set(None),
        };
        api_key::Entity::insert(key_model)
            .exec(conn)
            .await
            .map_err(|e| anyhow::anyhow!("insert api_key: {}", e))?;

        Ok((api_key_id, plaintext_key))
    }

    /// 输出 admin key 提示。完整 key 仅在交互终端展示(运维在场可立即保存);
    /// 管道/日志采集下 stdout 会被留存,只输出掩码避免凭证入库。
    #[cfg(feature = "auth")]
    fn print_bootstrap_admin_key(
        api_key_id: crawlrs::domain::id::Id,
        team_id: crawlrs::domain::id::Id,
        plaintext_key: &str,
    ) {
        use std::io::IsTerminal;
        if std::io::stdout().is_terminal() {
            println!("Created admin API key:");
            println!("  api_key_id: {}", api_key_id);
            println!("  team_id:    {}", team_id);
            println!("  api_key:    {}", plaintext_key);
            println!("  scopes:     read, write, admin");
            println!();
            println!("Use this key as Bearer token:");
            println!(
                "  curl -H 'Authorization: Bearer {}' http://localhost:8899/v1/teams/me",
                plaintext_key
            );
        } else {
            println!("Created admin API key:");
            println!("  api_key_id: {}", api_key_id);
            println!("  team_id:    {}", team_id);
            println!(
                "  api_key:    {} (masked; rerun in a terminal to display the full key)",
                crawlrs::common::mask_secret(plaintext_key)
            );
            println!("  scopes:     read, write, admin");
        }
    }

    /// Run pending database migrations and exit.
    ///
    /// 生产 schema 初始化入口(文档审计缺陷 #1):此前 `auto_migrate=false` 且无
    /// migrate 子命令,生产用户只能按 README 手工逐个 `psql -f migrations/postgres/*.sql`。
    /// `CRAWLRS_MIGRATIONS_DIR` 覆盖迁移**基目录**(含 `<dialect>/` 子目录),
    /// 缺省 `./migrations`;实际执行目录按编译 dialect 选择(与
    /// `create_pool` 的 auto_migrate 同一判定)。
    async fn start_migrate_service(app_state: &CrawlRsState) -> anyhow::Result<()> {
        use crawlrs::infrastructure::database::dbnexus_connection::{
            dialect_migrations_dir, MIGRATIONS_DIR_ENV,
        };

        let base = std::path::PathBuf::from(
            env::var(MIGRATIONS_DIR_ENV).unwrap_or_else(|_| "migrations".to_string()),
        );
        let dir = dialect_migrations_dir(&base).ok_or_else(|| {
            anyhow::anyhow!(
                "no db dialect feature (db-postgres/db-sqlite/db-mysql) compiled; \
                 cannot select migrations/<dialect>/ under {}",
                base.display()
            )
        })?;
        if !dir.is_dir() {
            anyhow::bail!(
                "migrations directory not found: {} (set {MIGRATIONS_DIR_ENV} to override the base dir)",
                dir.display()
            );
        }
        log::info!("Running database migrations from {}...", dir.display());
        // fluxweir-llm-gateway D9:专用历史表执行器(含存量基线回填),
        // 与 fluxweir 的 dbnexus_migrations 隔离;第三参为基目录,
        // 执行器内部按编译 dialect 投影 <dialect>/ 子目录
        let applied =
            crawlrs::infrastructure::database::dbnexus_connection::run_crawlrs_migrations(
                &app_state.db_pool(),
                true,
                Some(&base),
            )
            .await
            .map_err(|e| anyhow::anyhow!("migration failed: {e}"))?;
        log::info!("Database migrations complete: {applied} applied");
        println!("Migrations applied: {applied}");
        Ok(())
    }

    pub(crate) async fn run() -> anyhow::Result<()> {
        // 1. Load and configure settings
        let settings = load_runtime_settings()?;

        // 2. Initialize telemetry and metrics (inklog LoggerManager must be held alive)
        let _logger_manager = crawlrs::bootstrap::telemetry::init_all(&settings.logging)
            .await
            .map_err(|e| anyhow::anyhow!("Failed to initialize inklog logger: {}", e))?;

        // 移除 CRAWLRS_PROXY_URL 环境变量桥接。
        // 代理已统一由 EngineModule 构造 ProxyPool 注入 ReqwestEngine,
        // 通过 settings.proxy.urls 直接读取,无需通过环境变量中转。
        // 双重生效会导致:http_client 级别代理 + ReqwestEngine 级别代理 同时生效冲突。

        // 3. Build application state via trait-kit AsyncKit
        log::info!("Initializing application dependencies...");

        let mut kit = AsyncKit::new();
        kit.set_config(settings.clone());
        register_core_modules(&mut kit)?;

        let kit = kit
            .build()
            .await
            .map_err(|e| anyhow::anyhow!("build AsyncKit: {e}"))?;
        let app_state = CrawlRsState::from_kit(&kit)?;
        let http_client = kit
            .require::<HttpModule>()
            .map_err(|e| anyhow::anyhow!("require HttpModule: {e}"))?;

        log::info!("Application dependencies initialized successfully");

        // 4. Start service based on type
        dispatch_service(&app_state, settings, http_client).await
    }

    /// 加载并配置运行时设置。
    ///
    /// 1.5 初始化启动期 i18n 全局束(检测链决议 default_locale)。
    /// 必须先于 kit.build:RAG 配置校验消息等启动期出口经 Fluent 输出。
    /// 加载失败(locales 目录缺失)保持未初始化,各出口回退英文规范串。
    fn load_runtime_settings() -> anyhow::Result<Arc<crawlrs::config::settings::Settings>> {
        let is_production = env::var("CRAWLRS_ENV")
            .map(|v| v.eq_ignore_ascii_case("production") || v.eq_ignore_ascii_case("prod"))
            .unwrap_or(false);

        let (settings, _port) = crawlrs::bootstrap::config::load_and_configure(is_production)?;
        let settings = Arc::new(settings);

        if let Some(bundle) = crawlrs::i18n::build_startup_bundle(&settings.i18n) {
            crawlrs::i18n::init_startup_i18n(bundle);
        }

        Ok(settings)
    }

    /// 注册全部 DI 模块(顺序即依赖顺序)。
    fn register_core_modules(kit: &mut AsyncKit) -> anyhow::Result<()> {
        kit.register::<SettingsModule>()
            .map_err(|e| anyhow::anyhow!("register SettingsModule: {e}"))?;
        kit.register::<DatabaseModule>()
            .map_err(|e| anyhow::anyhow!("register DatabaseModule: {e}"))?;
        kit.register::<HttpModule>()
            .map_err(|e| anyhow::anyhow!("register HttpModule: {e}"))?;
        kit.register::<CacheModule>()
            .map_err(|e| anyhow::anyhow!("register CacheModule: {e}"))?;
        kit.register::<RepositoryModule>()
            .map_err(|e| anyhow::anyhow!("register RepositoryModule: {e}"))?;
        kit.register::<EngineModule>()
            .map_err(|e| anyhow::anyhow!("register EngineModule: {e}"))?;
        kit.register::<InfrastructureModule>()
            .map_err(|e| anyhow::anyhow!("register InfrastructureModule: {e}"))?;
        kit.register::<ServiceModule>()
            .map_err(|e| anyhow::anyhow!("register ServiceModule: {e}"))?;
        kit.register::<IdModule>().map_err(|e| {
            anyhow::anyhow!(
                "{}: {e}",
                crawlrs::i18n::tr_log("boot-register-id-module-failed")
            )
        })?;
        Ok(())
    }

    /// 按 `argv[1]` 选择执行人格并启动对应服务。
    async fn dispatch_service(
        app_state: &CrawlRsState,
        settings: Arc<crawlrs::config::settings::Settings>,
        http_client: Arc<reqwest::Client>,
    ) -> anyhow::Result<()> {
        match ServiceType::from_args() {
            ServiceType::Api => {
                start_api_service(app_state, settings).await?;
            }
            ServiceType::Worker => {
                start_worker_service(app_state, settings, http_client).await?;
            }
            ServiceType::Bootstrap => {
                run_bootstrap(app_state, &settings).await?;
            }
            ServiceType::Migrate => {
                start_migrate_service(app_state).await?;
            }
        }

        Ok(())
    }
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    app::run().await
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn tc_parse_service_type_api() {
        let result = parse_service_type(Some("api"));
        assert!(matches!(result, Ok(ServiceType::Api)));
    }

    #[test]
    fn tc_parse_service_type_worker() {
        let result = parse_service_type(Some("worker"));
        assert!(matches!(result, Ok(ServiceType::Worker)));
    }

    #[test]
    fn tc_parse_service_type_none_defaults_to_api() {
        let result = parse_service_type(None);
        assert!(matches!(result, Ok(ServiceType::Api)));
    }

    #[test]
    fn tc_parse_service_type_migrate() {
        let result = parse_service_type(Some("migrate"));
        assert!(matches!(result, Ok(ServiceType::Migrate)));
    }

    #[test]
    fn tc_parse_service_type_bootstrap() {
        let result = parse_service_type(Some("bootstrap"));
        assert!(matches!(result, Ok(ServiceType::Bootstrap)));
    }

    #[test]
    fn tc_parse_service_type_invalid_returns_error() {
        let result = parse_service_type(Some("invalid"));
        // ServiceType 未实现 Debug,使用 match 而非 unwrap_err
        match result {
            Err(msg) => {
                assert!(msg.contains("Invalid service type"), "got: {}", msg);
                assert!(msg.contains("invalid"), "got: {}", msg);
                assert!(
                    msg.contains("api") || msg.contains("worker"),
                    "got: {}",
                    msg
                );
            }
            Ok(_) => panic!("expected error for invalid service type, got Ok"),
        }
    }

    #[test]
    fn tc_parse_service_type_empty_string_returns_error() {
        let result = parse_service_type(Some(""));
        // ServiceType 未实现 Debug,使用 match 而非 unwrap_err
        match result {
            Err(msg) => {
                assert!(msg.contains("Invalid service type"), "got: {}", msg);
            }
            Ok(_) => panic!("expected error for empty string, got Ok"),
        }
    }

    #[test]
    fn tc_parse_service_type_case_sensitive() {
        // Service type 解析应区分大小写
        let result = parse_service_type(Some("API"));
        assert!(result.is_err(), "uppercase API should be invalid");

        let result = parse_service_type(Some("Worker"));
        assert!(result.is_err(), "mixed-case Worker should be invalid");
    }
}