mlsimport / includes / interface-mlsimport-import-task-execution-environment.php

interface-mlsimport-import-task-execution-environment.php in MLSImport: IDX Plugin & MLS Plugin for Real Estate Listings 7.2, at includes/interface-mlsimport-import-task-execution-environment.php

183 lines 6.1 KB

Raw Download Zip

1	<?php
2	/**
3	* System-boundary contract for Import Task execution.
4	*
5	* The execution module owns Import Run rules. Implementations of this contract
6	* only provide time, identity, and persistent WordPress run storage. Later TDD
7	* slices extend the same boundary when external MLS and listing writes enter
8	* the public run sequence.
9	*
10	* @package MLSImport
11	*/
12
13	if ( ! defined( 'ABSPATH' ) ) {
14	exit;
15	}
16
17	/**
18	* Supplies external operations without exposing execution internals.
19	*/
20	interface Mlsimport_Import_Task_Execution_Environment {
21
22	/**
23	* Create a unique identity for a newly requested Import Run.
24	*
25	* @return string Unique run identity.
26	*/
27	public function new_run_id(): string;
28
29	/**
30	* Return the current clock time used for activity and stale-run rules.
31	*
32	* @return int Unix timestamp.
33	*/
34	public function now(): int;
35
36	/**
37	* Atomically claim the one site-wide Import Run slot and save the run.
38	*
39	* @param array<string, mixed> $run Waiting run record.
40	* @param int $stale_before Heartbeats at or before this time are stale.
41	* @return bool True when the run owns the slot.
42	*/
43	public function claim_run( array $run, int $stale_before ): bool;
44
45	/**
46	* Read a previously accepted Import Run.
47	*
48	* @param string $run_id Run identity.
49	* @return array<string, mixed> Saved run, or an empty array when unavailable.
50	*/
51	public function read_run( string $run_id ): array;
52
53	/**
54	* Report whether a worker still owns the one site-wide Import Run slot.
55	*
56	* @param string $run_id Run identity.
57	* @return bool True only while this identity remains current.
58	*/
59	public function owns_run( string $run_id ): bool;
60
61	/**
62	* Persist state and progress changes for an active Import Run.
63	*
64	* @param string $run_id Run identity.
65	* @param array<string, mixed> $changes Changed run fields.
66	* @return void
67	*/
68	public function update_run( string $run_id, array $changes ): void;
69
70	/**
71	* Persist the final public result and release the site-wide slot.
72	*
73	* @param string $run_id Run identity.
74	* @param array<string, mixed> $result Final Import Run Result.
75	* @return void
76	*/
77	public function finish_run( string $run_id, array $result ): void;
78
79	/**
80	* Fetch one group of listings from the external MLS boundary.
81	*
82	* @param array<string, mixed> $run Active run record and request.
83	* @param int $skip Number of planned listings already handled.
84	* @param int $limit Maximum listings requested in this group.
85	* @return array<string, mixed> Response with success and data fields.
86	*/
87	public function fetch_listing_batch( array $run, int $skip, int $limit ): array;
88
89	/**
90	* Save one MLS listing through the existing theme-specific write boundary.
91	*
92	* @param array<string, mixed> $run Active run record and request.
93	* @param array<string, mixed> $listing One MLS listing payload.
94	* @return array<string, mixed> Response with success and error fields.
95	*/
96	public function save_listing( array $run, array $listing ): array;
97
98	/**
99	* Persist a Stop request for the active run belonging to an Import Task.
100	*
101	* Stop is final for the administrator: the implementation records the
102	* stopped status and releases the site-wide slot immediately, so a new
103	* import may start right away. A still-live worker discovers the stop at
104	* its next listing boundary and exits without overwriting that status.
105	*
106	* @param int $task_id Import Task identifier.
107	* @return bool True when a matching active run received the request.
108	*/
109	public function request_stop( int $task_id ): bool;
110
111	/**
112	* Report whether Stop has been requested for an active run.
113	*
114	* @param string $run_id Run identity.
115	* @return bool Stored Stop state.
116	*/
117	public function stop_requested( string $run_id ): bool;
118
119	/**
120	* Read the latest public progress and result for an Import Task.
121	*
122	* @param int $task_id Import Task identifier.
123	* @return array<string, mixed> Public status, or an empty array when absent.
124	*/
125	public function read_task_status( int $task_id ): array;
126
127	/**
128	* Queue the next background worker for an Import Run that hands off.
129	*
130	* Called from inside a still-running worker whose chunk time budget is
131	* spent. The implementation must only enqueue: it must not clean up
132	* queue state, because at hand-off time the current worker's own action
133	* is the one legitimately marked as running.
134	*
135	* @param string $run_id Run identity to continue.
136	* @return void
137	*/
138	public function enqueue_worker( string $run_id ): void;
139
140	/**
141	* Queue a replacement worker for a run whose worker chain went silent.
142	*
143	* Called from the watchdog, never from inside a worker. Unlike
144	* enqueue_worker(), the implementation first clears dead or stale queue
145	* entries for the worker hook — at revival time any recorded running
146	* action belongs to a killed process, and any pending action failed to
147	* dispatch — then queues a fresh worker for the run.
148	*
149	* @param string $run_id Run identity to continue.
150	* @return void
151	*/
152	public function revive_worker( string $run_id ): void;
153
154	/**
155	* Read the run currently holding the site-wide slot for one Import Task.
156	*
157	* @param int $task_id Import Task identifier.
158	* @return array<string, mixed> Active run record, or empty when the task
159	* holds no active run.
160	*/
161	public function read_active_run( int $task_id ): array;
162
163	/**
164	* Count listings changed in the automatic run's saved sync period.
165	*
166	* @param array<string, mixed> $run Active automatic run and request.
167	* @return array<string, mixed> Response with success, found, and error fields.
168	*/
169	public function count_listings( array $run ): array;
170
171	/**
172	* Advance one Import Task's successful automatic-sync time.
173	*
174	* The WordPress implementation preserves the agreed two-hour overlap while
175	* formatting and storing the new value.
176	*
177	* @param int $task_id Import Task identifier.
178	* @param int $completed_at Successful run completion timestamp.
179	* @return void
180	*/
181	public function advance_last_successful_sync_time( int $task_id, int $completed_at ): void;
182	}
183