404-solution / includes / ViewBuildOrchestratorInterface.php

ViewBuildOrchestratorInterface.php in 404 Solution 4.2.0, at includes/ViewBuildOrchestratorInterface.php

169 lines 4.9 KB

Raw Download Zip

1	<?php
2
3	if (!defined('ABSPATH')) {
4	exit;
5	}
6
7	/**
8	* Interface for the staged view-build pipeline and mutation watermark system.
9	*
10	* Extracted from DataAccess in Phase 7 of the DataAccess refactor.
11	* Absorbs 13 traits: ViewQueriesStaged, ViewBuildHelpers,
12	* ViewBuildStageCallbacks, ViewBuildLockAndCron, ViewBuildPhpEnvProbe,
13	* ViewBuildHostFailurePolicy, ViewBuildSessionEnvProbe,
14	* ViewBuildStageRunner, AdminMutationGate, ViewBuildStartedWatermark,
15	* ViewBuildAdaptive, ViewBuildForceRestart, MutationWatermarkSeam.
16	*
17	* @see docs/dataaccess-refactor-plan.md Phase 7.
18	*/
19	interface ABJ_404_Solution_ViewBuildOrchestratorInterface {
20
21	// --- ViewQueriesStaged (orchestrator entry point, staged build loop) ---
22
23	/** @return void */
24	public function claimForegroundViewBuildLease(): void;
25
26	/**
27	* @param string $sub
28	* @param array<string, mixed> $tableOptions
29	* @return array<int, array<string, mixed>>
30	*/
31	public function runRedirectsForViewStaged(string $sub, array $tableOptions): array;
32
33	/** @return bool */
34	public function viewDoneIsServeable(): bool;
35
36	/** @return int Unix timestamp, or 0. */
37	public function getViewDoneBuiltAtTimestamp(): int;
38
39	/** @return void */
40	public function markViewDoneBuildCompleted(): void;
41
42	/** @return array<string, mixed> */
43	public function getViewBuildProgress(): array;
44
45	/**
46	* @param bool $forceRebuild
47	* @return array<string, mixed>
48	*/
49	public function advanceViewBuildOnce(bool $forceRebuild = false): array;
50
51	/** @return array{ran:bool, reason:string, progress:array<string,mixed>} */
52	public function runPageLoadFallbackAdvance(): array;
53
54	/**
55	* @param string $sub
56	* @param array<string, mixed> $tableOptions
57	* @return int
58	*/
59	public function runRedirectsForViewCountStaged(string $sub, array $tableOptions): int;
60
61	/** @return void */
62	public function rebuildViewDoneInBackground(): void;
63
64	/** @return string */
65	public function reconcileStagedTablesAtRunnerStartup(): string;
66
67	// --- ViewBuildHelpers (progress options, SQL staging, state probes) ---
68
69	/**
70	* @param string $optionName
71	* @param mixed $expected
72	* @return bool
73	*/
74	public function verifyOptionWriteCoherent(string $optionName, $expected): bool;
75
76	/** @return void */
77	public function capturePrefixAtBuildStart(): void;
78
79	/** @return bool */
80	public function verifyPrefixUnchangedSinceStageOne(): bool;
81
82	/** @return void */
83	public function clearPrefixAtStageOne(): void;
84
85	/** @return array<string, mixed> */
86	public function probeSqlModeForBuild(): array;
87
88	/** @return array<string, mixed> */
89	public function detectAndAdjustSqlMode(): array;
90
91	/**
92	* @param string $url
93	* @param int $maxLength
94	* @return string
95	*/
96	public function sanitizeUrlBeforeInsert(string $url, int $maxLength = 0): string;
97
98	// --- ViewBuildLockAndCron (cross-request lock, cron scheduling) ---
99
100	/** @return bool */
101	public function verifyBuildLockSerializesWriter(): bool;
102
103	/**
104	* @param int $delaySeconds
105	* @return void
106	*/
107	public function scheduleViewDoneRebuild(int $delaySeconds = 1): void;
108
109	// --- ViewBuildPhpEnvProbe (PHP runtime constraints) ---
110
111	/** @return array<string, mixed> */
112	public function probePhpEnvironmentForBuild(): array;
113
114	/** @return bool */
115	public function probeSetTimeLimitAvailability(): bool;
116
117	/** @return int */
118	public function probeMemoryLimitForS9(): int;
119
120	/** @return array<string, mixed> */
121	public function probeFilesystemEnvironmentForBuild(): array;
122
123	// --- ViewBuildHostFailurePolicy (permanent error handling) ---
124
125	/** @return void */
126	public function clearStagedBuildDegradedState(): void;
127
128	/** @return bool */
129	public function reconcilePostStageElevenState(): bool;
130
131	// --- ViewBuildSessionEnvProbe (MySQL session health) ---
132
133	/** @return array<string, mixed> */
134	public function probeSessionVariablesAtS1Entry(): array;
135
136	// --- AdminMutationGate (watermark-based visibility gate) ---
137
138	/** @return void */
139	public function markViewDoneInvalidatedByAdminMutation(): void;
140
141	// --- ViewBuildForceRestart ---
142
143	/**
144	* @param int $lockTimeoutSeconds
145	* @return bool
146	*/
147	public function forceRestartViewBuild(int $lockTimeoutSeconds = 10): bool;
148
149	// --- MutationWatermarkSeam ---
150
151	/** @return int */
152	public function bumpMutationWatermark(): int;
153
154	// --- Bridge methods for ViewReadService ---
155
156	/** @return void */
157	public function invalidateViewDoneServeableCacheBridge(): void;
158
159	/** @return array<string, mixed> */
160	public function getStagedQueryOptionsForRead(): array;
161
162	/**
163	* @param string $shortName
164	* @param int $default
165	* @return int
166	*/
167	public function readBuildProgressOption(string $shortName, int $default = 0): int;
168	}
169