1	<?php
2
3	declare(strict_types=1);
4
5	namespace LambdaTwelve\OneRecord\Server\Spi;
6
7	use LambdaTwelve\OneRecord\Api\ActionRequest;
8	use LambdaTwelve\OneRecord\Api\ActionRequestType;
9	use LambdaTwelve\OneRecord\Api\RequestStatus;
10	use LambdaTwelve\OneRecord\Rdf\Iri;
11
12	/**
13	* Action requests of every type. They are never deleted: revoked and
14	* rejected ones stay readable and stay in the audit trail, as the spec requires.
15	*/
16	interface ActionRequestStore
17	{
18	/**
19	* Stores a new request. The server calls this exactly once per request and
20	* moves it on with transition() from then on. A later save() under the same
21	* IRI may replace what transition() changes (status, status history,
22	* errors); the type, payload, the objects and topic the request concerns,
23	* the requester and the request time are fixed by the first save, the SDK
24	* never changes them afterwards, and a store may rely on that for the
25	* query columns it keeps next to the document.
26	*/
27	public function save(ActionRequest $request): void;
28
29	/**
30	* Replaces the stored request only if its current status is $expectedCurrent:
31	* compare-and-set, so two workers deciding the same request cannot both win
32	* and a stale snapshot cannot overwrite a terminal state.
33	*
34	* @throws StoreException with kind STATUS_CONFLICT when the stored status differs, NOT_FOUND when absent
35	*/
36	public function transition(ActionRequest $request, RequestStatus $expectedCurrent): void;
37
38	public function get(Iri $iri): ?ActionRequest;
39
40	/**
41	* Change and verification requests about one object, oldest first: its audit trail.
42	*
43	* @return list<ActionRequest>
44	*/
45	public function auditTrail(Iri $logisticsObject, AuditTrailQuery $query): array;
46
47	/**
48	* Pending change requests about one object, for rejecting the others
49	* once one is accepted.
50	*
51	* @return list<ActionRequest>
52	*/
53	public function pendingChanges(Iri $logisticsObject): array;
54
55	/**
56	* Every request of a type in the accepted state: the active subscriptions
57	* and delegations. A SubscriptionStore built over this store derives its
58	* subscribers from here, whatever either store is implemented with.
59	*
60	* @return list<ActionRequest>
61	*/
62	public function accepted(ActionRequestType $type): array;
63	}