404-solution / includes / view-build / ViewReadServiceInterface.php

ViewReadServiceInterface.php in 404 Solution trunk, at includes/view-build/ViewReadServiceInterface.php

210 lines 7.3 KB

Raw Download Zip

1	<?php
2
3	if (!defined('ABSPATH')) {
4	exit;
5	}
6
7	/**
8	* Public surface of the admin view-read service.
9	*
10	* This was previously expressed as five segregated sub-interfaces
11	* (status-counts, list-read, snapshot-read, metadata, hits-lifecycle)
12	* aggregated by this composite. The segregation was never realized: every
13	* typed caller (DataAccess delegate, View, admin tables, REST/AJAX handlers,
14	* the extraction tests) depended on this composite, and no code ever depended
15	* on a narrow sub-interface. The sub-interfaces were therefore unrealized
16	* scaffolding and have been collapsed into this single interface. The method
17	* set is unchanged, so existing typed callers continue to compile.
18	*
19	* Methods are grouped by their former sub-interface for readability:
20	* - status counts + invalidation hooks
21	* - redirect-list reads (admin tables / export)
22	* - schema / capacity introspection + failure diagnostics
23	* - hits-table lifecycle hook
24	*/
25	interface ABJ_404_Solution_ViewReadServiceInterface {
26	const SORT_READINESS_READY = 'ready';
27	const SORT_READINESS_BACKFILL_PENDING = 'backfill-pending';
28	const SORT_READINESS_SCHEMA_UNAVAILABLE = 'schema-unavailable';
29
30	/* ---- status counts + invalidation hooks ---- */
31
32	/**
33	* @param bool $bypassCache Retained for compatibility; foreground reads are always cache-only.
34	* @param array<string, mixed> $tableOptions Retained for compatibility; never enables a foreground query.
35	* @return array<string, int>
36	*/
37	public function getRedirectStatusCounts($bypassCache = false, array $tableOptions = array()): array;
38
39	/**
40	* Same counts as getRedirectStatusCounts(), plus the freshness state that
41	* produced them, so a caller can tell "never computed on this site" apart
42	* from "computed and genuinely zero". The flat accessor above collapses
43	* both onto an absent key / a zero.
44	*
45	* State is one of ABJ_404_Solution_StatusCountsRefreshCoordinator::STATE_*.
46	*
47	* @return array{counts: array<string, int>, state: string}
48	*/
49	public function getRedirectStatusCountsResult(): array;
50
51	/**
52	* @return array<string, int>
53	*/
54	public function getRedirectHitCountHistogram(): array;
55
56	/**
57	* @param bool $bypassCache Retained for compatibility; foreground reads are always cache-only.
58	* @param array<string, mixed> $tableOptions Retained for compatibility; never enables a foreground query.
59	* @return array<string, int>
60	*/
61	public function getCapturedStatusCounts($bypassCache = false, array $tableOptions = array()): array;
62
63	/**
64	* Captured-404 counts plus their freshness state. See
65	* getRedirectStatusCountsResult().
66	*
67	* @return array{counts: array<string, int>, state: string}
68	*/
69	public function getCapturedStatusCountsResult(): array;
70
71	/** @return int\|null Null until the background count has been computed. */
72	public function getHighImpactCapturedCount(): ?int;
73
74	/** @return string */
75	public function buildHighImpactCapturedCountQuery(): string;
76
77	/**
78	* @template T
79	* @param callable():T $work
80	* @return T
81	*/
82	public function runWithDeferredInvalidation(callable $work);
83
84	/** @return void */
85	public function invalidateStatusCountsCache(): void;
86
87	/** @return void */
88	public function invalidateViewSnapshotCache(): void;
89
90	/** @return void */
91	public function clearRegexRedirectsCache(): void;
92
93	/* ---- redirect-list reads (admin tables / export) ---- */
94
95	/**
96	* @param int $logID
97	* @return int
98	*/
99	public function getLogsCount($logID);
100
101	/** @param string $tempFile @return void */
102	public function doRedirectsExport(string $tempFile): void;
103
104	/** @return iterable<int, array<string, mixed>> */
105	public function getRedirectsWithRegEx();
106
107	/** @return array<int, array<string, mixed>> */
108	public function getManualRedirectsWithRegexMetachars();
109
110	/**
111	* @param string $sub
112	* @param array<string, mixed> $tableOptions
113	* @return array<int\|string, mixed>
114	*/
115	public function getRedirectsForView($sub, $tableOptions);
116
117	/**
118	* Whether the most recent getRedirectsForView() result is NOT a trustworthy
119	* "genuinely empty" listing (pending build, errored read, or an empty
120	* snapshot contradicting the live source count).
121	*
122	* @return bool
123	*/
124	public function lastRedirectsViewReadWasIncomplete(): bool;
125
126	/**
127	* @param string $sub
128	* @param array<string, mixed> $tableOptions
129	* @return int Negative when the count query was incomplete or unavailable.
130	*/
131	public function getRedirectsForViewCount(string $sub, array $tableOptions): int;
132
133	/**
134	* Whether ordering the admin list by $orderby can be served index-ordered now
135	* (a narrow sort-key-backed sort whose column exists and whose backfill latch
136	* is set; non-key-backed sorts are always ready). The admin header uses this
137	* to disable the URL / Destination sort links on the captured tab during the
138	* post-upgrade backfill window.
139	*
140	* @param string $orderby UI orderby alias (url, final_dest, logshits, ...).
141	* @return bool
142	*/
143	public function isSortReadyForOrderby(string $orderby): bool;
144
145	/**
146	* Readiness status for ordering the admin list by $orderby. Sort-key-backed
147	* URL / Destination sorts can be ready, temporarily pending a backfill, or
148	* structurally unavailable because the backing column/index schema is absent.
149	* Non-key-backed sorts are always ready.
150	*
151	* @param string $orderby UI orderby alias (url, final_dest, logshits, ...).
152	* @return string One of the SORT_READINESS_* constants.
153	*/
154	public function sortReadinessStatusForOrderby(string $orderby): string;
155
156	/**
157	* Backfill progress (0..100) for $orderby's narrow sort key, for the admin
158	* "building the index" tooltip. Cheap: cursor wp_options read over an O(1)
159	* MAX(id) probe, never a COUNT over the captured rows.
160	*
161	* @param string $orderby UI orderby alias.
162	* @return int
163	*/
164	public function sortBackfillPercentForOrderby(string $orderby): int;
165
166	/**
167	* @param array<int, string> $postIDs
168	* @return array<int, mixed>
169	*/
170	public function getExtraDataToPermalinkSuggestions(array $postIDs): array;
171
172	/* ---- schema / capacity introspection + failure diagnostics ---- */
173
174	/** @return array<string, mixed> */
175	public function getTableEngines();
176
177	/** @return bool */
178	public function isMyISAMSupported(): bool;
179
180	/** @return int */
181	public function getCapturedCount();
182
183	/** @return array<int, string> */
184	public function getAllPostTypes();
185
186	/** @return int */
187	public function getLogDiskUsage();
188
189	/**
190	* @param array<int, int> $types
191	* @param int $trashed
192	* @return int
193	*/
194	public function getRecordCount($types = array(), $trashed = 0);
195
196	/**
197	* @param string $sub
198	* @param string $failedQuery
199	* @param array<string, mixed> $tableOptions
200	* @param array<string, mixed> $queryResult
201	* @return array<string, mixed>
202	*/
203	public function captureViewQueryFailureDiagnostics(string $sub, string $failedQuery, array $tableOptions, array $queryResult): array;
204
205	/* ---- hits-table lifecycle hook ---- */
206
207	/** @return void */
208	public function maybeUpdateRedirectsForViewHitsTable(): void;
209	}
210