fase(3): crawling module domain and application

src/modules/crawling/application/commands/StartCrawlCommand.ts

@@ -0,0 +1,54 @@
+import { UseCase } from '../../../../shared/application/UseCase';
+import { EventBus } from '../../../../shared/application/EventBus';
+import { Result, Ok, Err } from '../../../../shared/domain/Result';
+import { Url } from '../../domain/value-objects/Url';
+import { CrawlSession } from '../../domain/entities/CrawlSession';
+import { ICrawlSessionRepository } from '../../domain/ports/ICrawlSessionRepository';
+
+interface StartCrawlRequest {
+  url: string;
+  seed: number;
+  maxStates: number;
+  config?: Record<string, unknown>;
+}
+
+interface StartCrawlResponse {
+  sessionId: string;
+}
+
+export class StartCrawlCommand implements UseCase<StartCrawlRequest, StartCrawlResponse, string> {
+  constructor(
+    private readonly repository: ICrawlSessionRepository,
+    private readonly eventBus: EventBus
+  ) {}
+
+  async execute(request: StartCrawlRequest): Promise<Result<StartCrawlResponse, string>> {
+    const urlResult = Url.create(request.url);
+    if (!urlResult.ok) {
+      return Err(urlResult.error);
+    }
+
+    const sessionResult = CrawlSession.create({
+      url: request.url,
+      seed: request.seed,
+      maxStates: request.maxStates,
+      config: request.config,
+    });
+
+    if (!sessionResult.ok) {
+      return Err(sessionResult.error);
+    }
+
+    const session = sessionResult.value;
+
+    await this.repository.save(session);
+
+    const events = session.domainEvents;
+    for (const event of events) {
+      await this.eventBus.publish(event);
+    }
+    session.clearEvents();
+
+    return Ok({ sessionId: session.id.toString() });
+  }
+}

src/modules/crawling/application/commands/StopCrawlCommand.ts

@@ -0,0 +1,37 @@
+import { UseCase } from '../../../../shared/application/UseCase';
+import { EventBus } from '../../../../shared/application/EventBus';
+import { Result, Ok, Err } from '../../../../shared/domain/Result';
+import { UniqueId } from '../../../../shared/domain/UniqueId';
+import { ICrawlSessionRepository } from '../../domain/ports/ICrawlSessionRepository';
+
+interface StopCrawlRequest {
+  sessionId: string;
+}
+
+export class StopCrawlCommand implements UseCase<StopCrawlRequest, void, string> {
+  constructor(
+    private readonly repository: ICrawlSessionRepository,
+    private readonly eventBus: EventBus
+  ) {}
+
+  async execute(request: StopCrawlRequest): Promise<Result<void, string>> {
+    const id = UniqueId.from(request.sessionId);
+    const session = await this.repository.findById(id);
+
+    if (!session) {
+      return Err('Session not found');
+    }
+
+    session.stop();
+
+    await this.repository.update(session);
+
+    const events = session.domainEvents;
+    for (const event of events) {
+      await this.eventBus.publish(event);
+    }
+    session.clearEvents();
+
+    return Ok(undefined);
+  }
+}

src/modules/crawling/application/queries/GetSessionQuery.ts

@@ -0,0 +1,43 @@
+import { UseCase } from '../../../../shared/application/UseCase';
+import { Result, Ok, Err } from '../../../../shared/domain/Result';
+import { UniqueId } from '../../../../shared/domain/UniqueId';
+import { ICrawlSessionRepository } from '../../domain/ports/ICrawlSessionRepository';
+
+interface GetSessionRequest {
+  sessionId: string;
+}
+
+interface SessionDTO {
+  id: string;
+  url: string;
+  status: string;
+  seed: number;
+  maxStates: number;
+  statesVisited: number;
+  config: Record<string, unknown>;
+}
+
+export class GetSessionQuery implements UseCase<GetSessionRequest, SessionDTO, string> {
+  constructor(private readonly repository: ICrawlSessionRepository) {}
+
+  async execute(request: GetSessionRequest): Promise<Result<SessionDTO, string>> {
+    const id = UniqueId.from(request.sessionId);
+    const session = await this.repository.findById(id);
+
+    if (!session) {
+      return Err('Session not found');
+    }
+
+    const dto: SessionDTO = {
+      id: session.id.toString(),
+      url: session.url,
+      status: session.status,
+      seed: session.seed,
+      maxStates: session.maxStates,
+      statesVisited: session.statesVisited,
+      config: session.config,
+    };
+
+    return Ok(dto);
+  }
+}

src/modules/crawling/application/queries/ListSessionsQuery.ts

@@ -0,0 +1,35 @@
+import { UseCase } from '../../../../shared/application/UseCase';
+import { Result, Ok } from '../../../../shared/domain/Result';
+import { ICrawlSessionRepository } from '../../domain/ports/ICrawlSessionRepository';
+
+type ListSessionsRequest = Record<string, never>;
+
+interface SessionDTO {
+  id: string;
+  url: string;
+  status: string;
+  seed: number;
+  maxStates: number;
+  statesVisited: number;
+  config: Record<string, unknown>;
+}
+
+export class ListSessionsQuery implements UseCase<ListSessionsRequest, SessionDTO[], string> {
+  constructor(private readonly repository: ICrawlSessionRepository) {}
+
+  async execute(_request: ListSessionsRequest): Promise<Result<SessionDTO[], string>> {
+    const sessions = await this.repository.findAll();
+
+    const dtos: SessionDTO[] = sessions.map((session) => ({
+      id: session.id.toString(),
+      url: session.url,
+      status: session.status,
+      seed: session.seed,
+      maxStates: session.maxStates,
+      statesVisited: session.statesVisited,
+      config: session.config,
+    }));
+
+    return Ok(dtos);
+  }
+}

src/modules/crawling/domain/entities/CrawlAction.ts

@@ -0,0 +1,50 @@
+import { Entity } from '../../../../shared/domain/Entity';
+import { UniqueId } from '../../../../shared/domain/UniqueId';
+
+interface CrawlActionProps {
+  type: string;
+  selector?: string;
+  value?: string;
+  seed: number;
+  stateId: string;
+  sessionId: string;
+  sequenceOrder: number;
+}
+
+export class CrawlAction extends Entity<CrawlActionProps> {
+  private constructor(props: CrawlActionProps, id?: UniqueId) {
+    super(props, id);
+  }
+
+  static create(props: CrawlActionProps, id?: UniqueId): CrawlAction {
+    return new CrawlAction(props, id);
+  }
+
+  get type(): string {
+    return this.props.type;
+  }
+
+  get selector(): string | undefined {
+    return this.props.selector;
+  }
+
+  get value(): string | undefined {
+    return this.props.value;
+  }
+
+  get seed(): number {
+    return this.props.seed;
+  }
+
+  get stateId(): string {
+    return this.props.stateId;
+  }
+
+  get sessionId(): string {
+    return this.props.sessionId;
+  }
+
+  get sequenceOrder(): number {
+    return this.props.sequenceOrder;
+  }
+}

src/modules/crawling/domain/entities/CrawlSession.ts

@@ -0,0 +1,119 @@
+import { AggregateRoot } from '../../../../shared/domain/AggregateRoot';
+import { UniqueId } from '../../../../shared/domain/UniqueId';
+import { Result, Ok, Err } from '../../../../shared/domain/Result';
+import { Url } from '../value-objects/Url';
+import { CrawlStarted } from '../events/CrawlStarted';
+import { CrawlCompleted } from '../events/CrawlCompleted';
+import { CrawlFailed } from '../events/CrawlFailed';
+
+type SessionStatusValue = 'running' | 'completed' | 'failed' | 'stopped';
+
+interface CrawlSessionProps {
+  url: string;
+  status: SessionStatusValue;
+  seed: number;
+  maxStates: number;
+  statesVisited: number;
+  config: Record<string, unknown>;
+}
+
+export interface CreateCrawlSessionRequest {
+  url: string;
+  seed: number;
+  maxStates: number;
+  config?: Record<string, unknown>;
+}
+
+export class CrawlSession extends AggregateRoot<CrawlSessionProps> {
+  private constructor(props: CrawlSessionProps, id?: UniqueId) {
+    super(props, id);
+  }
+
+  static create(request: CreateCrawlSessionRequest): Result<CrawlSession, string> {
+    const urlResult = Url.create(request.url);
+    if (!urlResult.ok) {
+      return Err(urlResult.error);
+    }
+
+    const props: CrawlSessionProps = {
+      url: request.url,
+      status: 'running',
+      seed: request.seed,
+      maxStates: request.maxStates,
+      statesVisited: 0,
+      config: request.config ?? {},
+    };
+
+    const session = new CrawlSession(props);
+
+    session.addDomainEvent(
+      new CrawlStarted(session.id.toString(), {
+        url: request.url,
+        seed: request.seed,
+        maxStates: request.maxStates,
+      })
+    );
+
+    return Ok(session);
+  }
+
+  get url(): string {
+    return this.props.url;
+  }
+
+  get status(): SessionStatusValue {
+    return this.props.status;
+  }
+
+  get seed(): number {
+    return this.props.seed;
+  }
+
+  get maxStates(): number {
+    return this.props.maxStates;
+  }
+
+  get statesVisited(): number {
+    return this.props.statesVisited;
+  }
+
+  get config(): Record<string, unknown> {
+    return this.props.config;
+  }
+
+  incrementStatesVisited(): void {
+    this.props = { ...this.props, statesVisited: this.props.statesVisited + 1 };
+  }
+
+  complete(): void {
+    this.props = { ...this.props, status: 'completed' };
+    this.addDomainEvent(
+      new CrawlCompleted(this.id.toString(), {
+        url: this.props.url,
+        statesVisited: this.props.statesVisited,
+      })
+    );
+  }
+
+  fail(reason: string): void {
+    this.props = { ...this.props, status: 'failed' };
+    this.addDomainEvent(
+      new CrawlFailed(this.id.toString(), {
+        url: this.props.url,
+        reason,
+        statesVisited: this.props.statesVisited,
+      })
+    );
+  }
+
+  stop(): void {
+    this.props = { ...this.props, status: 'stopped' };
+    this.addDomainEvent(
+      new CrawlCompleted(this.id.toString(), {
+        url: this.props.url,
+        statesVisited: this.props.statesVisited,
+        stopped: true,
+      })
+    );
+  }
+}

src/modules/crawling/domain/entities/CrawlState.ts

@@ -0,0 +1,45 @@
+import { Entity } from '../../../../shared/domain/Entity';
+import { UniqueId } from '../../../../shared/domain/UniqueId';
+
+interface CrawlStateProps {
+  url: string;
+  title: string;
+  domSnapshot: string;
+  visitCount: number;
+  stateId: string;
+  sessionId: string;
+}
+
+export class CrawlState extends Entity<CrawlStateProps> {
+  private constructor(props: CrawlStateProps, id?: UniqueId) {
+    super(props, id);
+  }
+
+  static create(props: CrawlStateProps, id?: UniqueId): CrawlState {
+    return new CrawlState(props, id);
+  }
+
+  get url(): string {
+    return this.props.url;
+  }
+
+  get title(): string {
+    return this.props.title;
+  }
+
+  get domSnapshot(): string {
+    return this.props.domSnapshot;
+  }
+
+  get visitCount(): number {
+    return this.props.visitCount;
+  }
+
+  get stateId(): string {
+    return this.props.stateId;
+  }
+
+  get sessionId(): string {
+    return this.props.sessionId;
+  }
+}

src/modules/crawling/domain/events/ActionExecuted.ts

@@ -0,0 +1,13 @@
+import { randomUUID } from 'crypto';
+import { DomainEvent } from '../../../../shared/domain/DomainEvent';
+
+export class ActionExecuted implements DomainEvent {
+  readonly eventId = randomUUID();
+  readonly eventName = 'crawl.action_executed';
+  readonly occurredOn = new Date();
+
+  constructor(
+    readonly aggregateId: string,
+    readonly payload: Record<string, unknown>
+  ) {}
+}

src/modules/crawling/domain/events/CrawlCompleted.ts

@@ -0,0 +1,13 @@
+import { randomUUID } from 'crypto';
+import { DomainEvent } from '../../../../shared/domain/DomainEvent';
+
+export class CrawlCompleted implements DomainEvent {
+  readonly eventId = randomUUID();
+  readonly eventName = 'crawl.completed';
+  readonly occurredOn = new Date();
+
+  constructor(
+    readonly aggregateId: string,
+    readonly payload: Record<string, unknown>
+  ) {}
+}

src/modules/crawling/domain/events/CrawlFailed.ts

@@ -0,0 +1,13 @@
+import { randomUUID } from 'crypto';
+import { DomainEvent } from '../../../../shared/domain/DomainEvent';
+
+export class CrawlFailed implements DomainEvent {
+  readonly eventId = randomUUID();
+  readonly eventName = 'crawl.failed';
+  readonly occurredOn = new Date();
+
+  constructor(
+    readonly aggregateId: string,
+    readonly payload: Record<string, unknown>
+  ) {}
+}

src/modules/crawling/domain/events/CrawlStarted.ts

@@ -0,0 +1,13 @@
+import { randomUUID } from 'crypto';
+import { DomainEvent } from '../../../../shared/domain/DomainEvent';
+
+export class CrawlStarted implements DomainEvent {
+  readonly eventId = randomUUID();
+  readonly eventName = 'crawl.started';
+  readonly occurredOn = new Date();
+
+  constructor(
+    readonly aggregateId: string,
+    readonly payload: Record<string, unknown>
+  ) {}
+}

src/modules/crawling/domain/events/StateDiscovered.ts

@@ -0,0 +1,13 @@
+import { randomUUID } from 'crypto';
+import { DomainEvent } from '../../../../shared/domain/DomainEvent';
+
+export class StateDiscovered implements DomainEvent {
+  readonly eventId = randomUUID();
+  readonly eventName = 'crawl.state_discovered';
+  readonly occurredOn = new Date();
+
+  constructor(
+    readonly aggregateId: string,
+    readonly payload: Record<string, unknown>
+  ) {}
+}

src/modules/crawling/domain/ports/ICrawlSessionRepository.ts

@@ -0,0 +1,9 @@
+import { CrawlSession } from '../entities/CrawlSession';
+import { UniqueId } from '../../../../shared/domain/UniqueId';
+
+export interface ICrawlSessionRepository {
+  save(session: CrawlSession): Promise<void>;
+  findById(id: UniqueId): Promise<CrawlSession | null>;
+  findAll(): Promise<CrawlSession[]>;
+  update(session: CrawlSession): Promise<void>;
+}

src/modules/crawling/domain/ports/ICrawlerEngine.ts

@@ -0,0 +1,9 @@
+import { IState, IAction, IObservation } from '../../../../core/interfaces';
+
+export interface ICrawlerEngine {
+  launch(url: string): Promise<void>;
+  close(): Promise<void>;
+  discoverActions(state: IState): Promise<IAction[]>;
+  executeAction(action: IAction): Promise<IObservation>;
+  captureState(): Promise<IState>;
+}

src/modules/crawling/domain/ports/IStateRepository.ts

@@ -0,0 +1,10 @@
+import { CrawlState } from '../entities/CrawlState';
+import { UniqueId } from '../../../../shared/domain/UniqueId';
+
+export interface IStateRepository {
+  save(state: CrawlState): Promise<void>;
+  findById(id: UniqueId): Promise<CrawlState | null>;
+  findAll(): Promise<CrawlState[]>;
+  findBySessionId(sessionId: string): Promise<CrawlState[]>;
+  update(state: CrawlState): Promise<void>;
+}

src/modules/crawling/domain/value-objects/Selector.ts

@@ -0,0 +1,23 @@
+import { ValueObject } from '../../../../shared/domain/ValueObject';
+import { Result, Ok, Err } from '../../../../shared/domain/Result';
+
+interface SelectorProps {
+  value: string;
+}
+
+export class Selector extends ValueObject<SelectorProps> {
+  private constructor(props: SelectorProps) {
+    super(props);
+  }
+
+  static create(raw: string): Result<Selector, string> {
+    if (!raw || raw.trim().length === 0) {
+      return Err('Selector must not be empty');
+    }
+    return Ok(new Selector({ value: raw.trim() }));
+  }
+
+  toString(): string {
+    return this.props.value;
+  }
+}

src/modules/crawling/domain/value-objects/SessionStatus.ts

@@ -0,0 +1,27 @@
+import { ValueObject } from '../../../../shared/domain/ValueObject';
+import { Result, Ok, Err } from '../../../../shared/domain/Result';
+
+type StatusValue = 'running' | 'completed' | 'failed' | 'stopped';
+
+interface SessionStatusProps {
+  value: StatusValue;
+}
+
+const VALID_STATUSES: StatusValue[] = ['running', 'completed', 'failed', 'stopped'];
+
+export class SessionStatus extends ValueObject<SessionStatusProps> {
+  private constructor(props: SessionStatusProps) {
+    super(props);
+  }
+
+  static create(val: string): Result<SessionStatus, string> {
+    if (!VALID_STATUSES.includes(val as StatusValue)) {
+      return Err(`Invalid session status: "${val}". Must be one of: ${VALID_STATUSES.join(', ')}`);
+    }
+    return Ok(new SessionStatus({ value: val as StatusValue }));
+  }
+
+  getValue(): StatusValue {
+    return this.props.value;
+  }
+}

src/modules/crawling/domain/value-objects/Url.ts

@@ -0,0 +1,27 @@
+import { ValueObject } from '../../../../shared/domain/ValueObject';
+import { Result, Ok, Err } from '../../../../shared/domain/Result';
+
+interface UrlProps {
+  value: string;
+}
+
+export class Url extends ValueObject<UrlProps> {
+  private constructor(props: UrlProps) {
+    super(props);
+  }
+
+  static create(raw: string): Result<Url, string> {
+    if (!raw || raw.trim().length === 0) {
+      return Err('URL must not be empty');
+    }
+    const trimmed = raw.trim();
+    if (!trimmed.startsWith('http://') && !trimmed.startsWith('https://')) {
+      return Err('URL must start with http:// or https://');
+    }
+    return Ok(new Url({ value: trimmed }));
+  }
+
+  toString(): string {
+    return this.props.value;
+  }
+}

src/modules/crawling/index.ts

@@ -0,0 +1,10 @@
+export * from './domain/entities/CrawlSession';
+export * from './domain/entities/CrawlState';
+export * from './domain/entities/CrawlAction';
+export * from './domain/ports/ICrawlerEngine';
+export * from './domain/ports/ICrawlSessionRepository';
+export * from './domain/ports/IStateRepository';
+export * from './application/commands/StartCrawlCommand';
+export * from './application/commands/StopCrawlCommand';
+export * from './application/queries/GetSessionQuery';
+export * from './application/queries/ListSessionsQuery';