From c9192a76ba3f819b03f6bcaa921511618475eecd Mon Sep 17 00:00:00 2001 From: Ruben van der Linde Date: Sat, 21 Nov 2026 18:53:00 +0100 Subject: [PATCH] feat(hydra-gates): ship the values ObjectServiceInterface names, and ObjectFileReaderInterface Copies openregister's lib/Contract byte for byte after its task 7.2: the thirteen value classes the published ObjectServiceInterface now names, the widened ObjectServiceInterface, and ObjectFileReaderInterface, which was in lib/Contract but missing here and kept gate 67 red. Assisted-by: ClaudeCode:claude-opus-5-5 --- hydra-gates/README.md | 44 +++- hydra-gates/contracts/BulkBatchDefaults.php | 48 ++++ hydra-gates/contracts/BulkSaveOptions.php | 52 +++++ hydra-gates/contracts/LockRequest.php | 64 ++++++ hydra-gates/contracts/LockRunStep.php | 45 ++++ hydra-gates/contracts/ObjectDeletion.php | 76 +++++++ .../contracts/ObjectFileReaderInterface.php | 53 +++++ hydra-gates/contracts/ObjectFindOptions.php | 55 +++++ hydra-gates/contracts/ObjectFindTarget.php | 80 +++++++ hydra-gates/contracts/ObjectPatch.php | 56 +++++ hydra-gates/contracts/ObjectSaveOptions.php | 61 +++++ .../contracts/ObjectServiceInterface.php | 211 ++++++++---------- .../contracts/ObjectValidationVerdict.php | 78 +++++++ hydra-gates/contracts/SaveActor.php | 58 +++++ hydra-gates/contracts/SavePolicy.php | 55 +++++ hydra-gates/contracts/UnlockRequest.php | 49 ++++ 16 files changed, 963 insertions(+), 122 deletions(-) create mode 100644 hydra-gates/contracts/BulkBatchDefaults.php create mode 100644 hydra-gates/contracts/BulkSaveOptions.php create mode 100644 hydra-gates/contracts/LockRequest.php create mode 100644 hydra-gates/contracts/LockRunStep.php create mode 100644 hydra-gates/contracts/ObjectDeletion.php create mode 100644 hydra-gates/contracts/ObjectFileReaderInterface.php create mode 100644 hydra-gates/contracts/ObjectFindOptions.php create mode 100644 hydra-gates/contracts/ObjectFindTarget.php create mode 100644 hydra-gates/contracts/ObjectPatch.php create mode 100644 hydra-gates/contracts/ObjectSaveOptions.php create mode 100644 hydra-gates/contracts/ObjectValidationVerdict.php create mode 100644 hydra-gates/contracts/SaveActor.php create mode 100644 hydra-gates/contracts/SavePolicy.php create mode 100644 hydra-gates/contracts/UnlockRequest.php diff --git a/hydra-gates/README.md b/hydra-gates/README.md index c4479408e..1bd447408 100644 --- a/hydra-gates/README.md +++ b/hydra-gates/README.md @@ -192,6 +192,20 @@ can typehint it under PHPUnit without the OpenRegister app installed: | `RegisterSlugResolverInterface.php` | interface | finds the slug a register answers to on this instance | | `RegisterSlugResolution.php` | **final class** | the value `resolve()` returns | | `EmailLinkReaderInterface.php` | interface | reads the Nextcloud Mail messages linked to an object | +| `ObjectFileReaderInterface.php` | interface | reads the files attached to an object | +| `ObjectSaveOptions.php` | class | where and how `saveObject()` stores an object | +| `BulkSaveOptions.php` | class | where and how `saveObjects()` stores a batch | +| `ObjectFindOptions.php` | class | register, schema, extend, files, render and audit of a read | +| `ObjectDeletion.php` | class | the object `deleteObject()` removes, and how | +| `ObjectPatch.php` | class | the partial data `patchObject()` merges | +| `LockRequest.php` | class | the lock `lockObject()` takes | +| `UnlockRequest.php` | class | the lock `unlockObject()` releases | +| `ObjectValidationVerdict.php` | class | the answer of `validateObject()` | +| `ObjectFindTarget.php` | class | the register and schema scope the values above carry | +| `SaveActor.php` | class | who a save acts as | +| `SavePolicy.php` | class | events, validation and insert-only choices of a save | +| `BulkBatchDefaults.php` | class | the batch defaults of a bulk save | +| `LockRunStep.php` | class | the flow run step that takes a lock | Each file is a byte-for-byte copy of the same file in openregister's `lib/Contract/`. No namespace rewrite, no header, no index. Gate 67 fails the @@ -208,6 +222,20 @@ shipped" until the lock moves. `RegisterSlugResolution` and `RegisterSlugResolve landed in openregister#3571, here in #739, and first shipped in v1.18.0. `EmailLinkReaderInterface` first shipped in v1.19.0, so an openregister lock on v1.18.0 still fails gate 67 locally. +The thirteen value classes (`ObjectSaveOptions` to `LockRunStep` above) are the +values `ObjectServiceInterface` names in its signatures, published by +openregister's task 7.2 so the contract is self-contained. openregister keeps +their old names, `OCA\OpenRegister\Kernel\Contracts\Value\`, as +deprecated subclasses, so values built under the old name are still accepted. +A test double that `implements ObjectServiceInterface` (or extends +openregister's `ObjectService`) must type those parameters with the published +name or wider; one typed with only the old Kernel name is narrower and fatals at +class load. Typing it `ObjectSaveOptions|PublishedObjectSaveOptions` (old name +or published name) loads against both the old and the new contract, because PHP +matches a union member by name without loading the other class. +`ObjectFileReaderInterface.php` was in openregister's `lib/Contract/` but not +here, which kept gate 67 red until it shipped. + They are **not** autoloaded. This package used to declare ```json @@ -226,7 +254,7 @@ A consumer that needs these contracts requires them from its own test bootstrap, behind a guard: ```php -foreach (['ObjectEntityInterface', 'ObjectServiceInterface', 'RegisterSlugResolution', 'RegisterSlugResolverInterface', 'EmailLinkReaderInterface'] as $contract) { +foreach (['ObjectEntityInterface', 'ObjectServiceInterface', 'RegisterSlugResolution', 'RegisterSlugResolverInterface', 'EmailLinkReaderInterface', 'ObjectFileReaderInterface', 'ObjectFindTarget', 'SaveActor', 'SavePolicy', 'BulkBatchDefaults', 'LockRunStep', 'ObjectSaveOptions', 'BulkSaveOptions', 'LockRequest', 'UnlockRequest', 'ObjectFindOptions', 'ObjectDeletion', 'ObjectPatch', 'ObjectValidationVerdict'] as $contract) { $fqcn = '\\OCA\\OpenRegister\\Contract\\' . $contract; if (interface_exists($fqcn) === false && class_exists($fqcn) === false) { $shipped = __DIR__ . '/../vendor/conduction/hydra-gates/hydra-gates/contracts/' . $contract . '.php'; @@ -277,6 +305,20 @@ the autoloader is precisely the defect this change removed. + + + + + + + + + + + + + + ``` diff --git a/hydra-gates/contracts/BulkBatchDefaults.php b/hydra-gates/contracts/BulkBatchDefaults.php new file mode 100644 index 000000000..962b975ba --- /dev/null +++ b/hydra-gates/contracts/BulkBatchDefaults.php @@ -0,0 +1,48 @@ + + * @copyright 2026 Conduction B.V. + * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12 + * + * @link https://OpenRegister.app + * + * @spec openspec/specs/rbac-zaaktype/spec.md + */ + +namespace OCA\OpenRegister\Contract; + +use OCA\OpenRegister\Db\Register; +use OCA\OpenRegister\Db\Schema; + +/** + * The default register and schema of one bulk batch, as the caller passed them. + * + * No strict_types: SaveObjects declares none, and these values arrive from it. + * + * @spec openspec/specs/rbac-zaaktype/spec.md + */ +class BulkBatchDefaults { + + /** + * Constructor. + * + * @param Register|string|int|null $register Default register context. + * @param Schema|string|int|null $schema Default schema context (null = mixed-schema). + */ + public function __construct( + public readonly Register|string|int|null $register=null, + public readonly Schema|string|int|null $schema=null, + ) { + }//end __construct() +}//end class diff --git a/hydra-gates/contracts/BulkSaveOptions.php b/hydra-gates/contracts/BulkSaveOptions.php new file mode 100644 index 000000000..b0535d081 --- /dev/null +++ b/hydra-gates/contracts/BulkSaveOptions.php @@ -0,0 +1,52 @@ + + * @copyright 2026 Conduction B.V. + * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12 + * + * @link https://OpenRegister.app + * + * @spec openspec/specs/object-lifecycle/spec.md + */ + +namespace OCA\OpenRegister\Contract; + +/** + * How one SaveObjects::saveObjects() call saves its rows, apart from its RBAC and multitenancy flags. + * + * No strict_types: SaveObjects declares none, and these values arrive from it. + * + * @spec openspec/specs/object-lifecycle/spec.md + */ +class BulkSaveOptions { + + /** + * Constructor. + * + * @param BulkBatchDefaults $defaults The register and schema for every row that names none. + * @param bool $validation Whether to validate rows against their schema. + * @param bool $events Whether to dispatch object lifecycle events. + * @param bool $audit Whether to write audit trail rows for the persisted objects. + * + * @spec openspec/specs/object-lifecycle/spec.md + */ + public function __construct( + public readonly BulkBatchDefaults $defaults=new BulkBatchDefaults(), + public readonly bool $validation=false, + public readonly bool $events=false, + public readonly bool $audit=true, + ) { + }//end __construct() +}//end class diff --git a/hydra-gates/contracts/LockRequest.php b/hydra-gates/contracts/LockRequest.php new file mode 100644 index 000000000..4a2957640 --- /dev/null +++ b/hydra-gates/contracts/LockRequest.php @@ -0,0 +1,64 @@ + + * @copyright 2026 Conduction B.V. + * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12 + * + * @version GIT: + * + * @link https://OpenRegister.app + * + * @spec openspec/specs/object-interactions/spec.md + */ + +declare(strict_types=1); + +namespace OCA\OpenRegister\Contract; + + +/** + * The arguments of LockHandler::lock(), carried together through its steps. + */ +class LockRequest { + + /** + * Flow run taking the lock, for a run-scoped lock. + * + * @var string|null + */ + public readonly ?string $runUuid; + + /** + * Flow node that took it, recorded for the sweep. + * + * @var string|null + */ + public readonly ?string $nodeId; + + /** + * Constructor + * + * @param string $identifier Object ID or UUID. + * @param string|null $process What the lock is taken for. + * @param int|null $duration Lock duration in seconds. + * @param LockRunStep $runStep The flow run and node taking it, both null outside a run. + */ + public function __construct( + public readonly string $identifier, + public readonly ?string $process=null, + public readonly ?int $duration=null, + LockRunStep $runStep=new LockRunStep(runUuid: null, nodeId: null), + ) { + $this->runUuid = $runStep->runUuid; + $this->nodeId = $runStep->nodeId; + }//end __construct() +}//end class diff --git a/hydra-gates/contracts/LockRunStep.php b/hydra-gates/contracts/LockRunStep.php new file mode 100644 index 000000000..4aac9004c --- /dev/null +++ b/hydra-gates/contracts/LockRunStep.php @@ -0,0 +1,45 @@ + + * @copyright 2026 Conduction B.V. + * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12 + * + * @version GIT: + * + * @link https://OpenRegister.app + * + * @spec openspec/specs/object-interactions/spec.md + */ + +declare(strict_types=1); + +namespace OCA\OpenRegister\Contract; + +/** + * Which flow run took a lock, and from which node, as LockHandler::lock() was told. + * + * @spec openspec/specs/object-interactions/spec.md + */ +class LockRunStep { + + /** + * Constructor + * + * @param string|null $runUuid Flow run taking the lock, for a run-scoped lock. + * @param string|null $nodeId Flow node that took it, recorded for the sweep. + */ + public function __construct( + public readonly ?string $runUuid, + public readonly ?string $nodeId, + ) { + }//end __construct() +}//end class diff --git a/hydra-gates/contracts/ObjectDeletion.php b/hydra-gates/contracts/ObjectDeletion.php new file mode 100644 index 000000000..3d9f3c30d --- /dev/null +++ b/hydra-gates/contracts/ObjectDeletion.php @@ -0,0 +1,76 @@ + + * @copyright 2026 Conduction B.V. + * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12 + * + * @version GIT: + * + * @link https://www.OpenRegister.app + * + * @spec openspec/specs/object-lifecycle/spec.md + */ + +declare(strict_types=1); + +namespace OCA\OpenRegister\Contract; + +use OCP\IUser; + +/** + * One delete a caller asks for: the object, where to find it, who acts and whether the row is destroyed. + * + * @spec openspec/specs/object-lifecycle/spec.md + */ +class ObjectDeletion { + + /** + * Constructor. + * + * @param string $uuid The UUID of the object to delete. + * @param ObjectFindTarget $target The register and schema the caller named. When both are + * set the lookup targets exactly that magic table. + * @param IUser|null $currentUser Explicit acting user for the RBAC `delete` check, or null + * for the session user. A sessionless caller (flow run, cron, + * import pipeline) must set one: anonymous is default-deny. + * @param bool $permanent Destroy the row rather than tombstone it, so its identifier + * becomes reusable. Reserve it for rows that are a claim rather + * than a record (openregister#2459). + * @param \Closure|null $reach Whether the delete may change an object it reaches through a + * reference (a cascade child, or a dependent the onDelete rules + * delete or rewrite), asked with that object's uuid. A dependent + * it refuses blocks the delete. Null lets the rules decide alone. + * + * @SuppressWarnings(PHPMD.BooleanArgumentFlag) Soft delete is the default every caller gets. + * + * @spec openspec/specs/object-lifecycle/spec.md + */ + public function __construct( + public readonly string $uuid, + public readonly ObjectFindTarget $target=new ObjectFindTarget(), + public readonly ?IUser $currentUser=null, + public readonly bool $permanent=false, + public readonly ?\Closure $reach=null, + ) { + }//end __construct() + + /** + * Whether the caller named both a register and a schema, so the lookup is scoped to one table. + * + * @return bool + * + * @spec openspec/specs/object-lifecycle/spec.md + */ + public function isScoped(): bool { + return $this->target->register !== null && $this->target->schema !== null; + }//end isScoped() +}//end class diff --git a/hydra-gates/contracts/ObjectFileReaderInterface.php b/hydra-gates/contracts/ObjectFileReaderInterface.php new file mode 100644 index 000000000..7f09debc3 --- /dev/null +++ b/hydra-gates/contracts/ObjectFileReaderInterface.php @@ -0,0 +1,53 @@ + + * @copyright 2026 Conduction B.V. + * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12 + * + * @link https://www.OpenRegister.nl + */ + +declare(strict_types=1); + +namespace OCA\OpenRegister\Contract; + +/** + * Reads the files attached to an object. + * + * @spec openspec/specs/file-actions/spec.md + */ +interface ObjectFileReaderInterface { + + /** + * The files attached to an object, as Nextcloud file nodes. + * + * The caller checks that its user may see the object before it asks: the + * read itself is by object uuid and applies no object rights. An object + * that never had a files folder has no files and answers an empty list. + * Folders inside the object's folder are left out; only files are listed. + * + * @param string $objectUuid The object's uuid. + * + * @return array The files, in the folder's order. + * + * @throws \OCP\AppFramework\Db\DoesNotExistException When no object has that uuid. + * + * @spec openspec/specs/file-actions/spec.md + */ + public function getObjectFiles(string $objectUuid): array; +}//end interface diff --git a/hydra-gates/contracts/ObjectFindOptions.php b/hydra-gates/contracts/ObjectFindOptions.php new file mode 100644 index 000000000..77a662fdd --- /dev/null +++ b/hydra-gates/contracts/ObjectFindOptions.php @@ -0,0 +1,55 @@ + + * @copyright 2026 Conduction B.V. + * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12 + * + * @link https://www.OpenRegister.nl + */ + +declare(strict_types=1); + +namespace OCA\OpenRegister\Contract; + +use OCA\OpenRegister\Kernel\Contracts\RegisterInterface; +use OCA\OpenRegister\Kernel\Contracts\SchemaInterface; + +/** + * The optional part of a single-object read: find() and findSilent(). + * + * Without a register and schema the read searches every table. `render` and + * `audit` apply to find() only; findSilent() never renders or audits. + * + * @spec exclude ADR-011 parameter object of the object read, not a capability of its own + */ +class ObjectFindOptions { + + /** + * Constructor + * + * @param RegisterInterface|string|int|null $register The register, or its id, uuid or slug. + * @param SchemaInterface|string|int|null $schema The schema, or its id, uuid or slug. + * @param array|null $extend Properties to extend the object with. + * @param bool $files Include file information. + * @param bool $render Render the entity before returning it. + * @param bool $audit Write an audit-trail row for this read. + */ + public function __construct( + public readonly RegisterInterface|string|int|null $register=null, + public readonly SchemaInterface|string|int|null $schema=null, + public readonly ?array $extend=[], + public readonly bool $files=false, + public readonly bool $render=true, + public readonly bool $audit=true, + ) { + }//end __construct() +}//end class diff --git a/hydra-gates/contracts/ObjectFindTarget.php b/hydra-gates/contracts/ObjectFindTarget.php new file mode 100644 index 000000000..c9f0d6de1 --- /dev/null +++ b/hydra-gates/contracts/ObjectFindTarget.php @@ -0,0 +1,80 @@ + + * @copyright 2026 Conduction B.V. + * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12 + * + * @version GIT: + * + * @link https://www.OpenRegister.app + * + * @spec exclude Value object of the ObjectService::find() facade; read behaviour owned by object-interactions. + */ + +declare(strict_types=1); + +namespace OCA\OpenRegister\Contract; + +use OCA\OpenRegister\Db\Register; +use OCA\OpenRegister\Db\Schema; +use OCA\OpenRegister\Kernel\Contracts\RegisterInterface; +use OCA\OpenRegister\Kernel\Contracts\SchemaInterface; + +/** + * The register and schema one ObjectService::find() call names, as the caller gave them. + * + * The named constructor builds the class it is called on, so it keeps one constructor for every subclass. + * + * @phpstan-consistent-constructor + * @psalm-consistent-constructor + * + * @spec exclude Value object of the ObjectService::find() facade; read behaviour owned by object-interactions. + */ +class ObjectFindTarget { + + /** + * Constructor. + * + * @param Register|string|int|null $register The register object or its ID/UUID. + * @param Schema|string|int|null $schema The schema object or its ID/UUID. + * + * @spec exclude Value object of the ObjectService::find() facade; read behaviour owned by object-interactions. + */ + public function __construct( + public readonly Register|string|int|null $register=null, + public readonly Schema|string|int|null $schema=null, + ) { + }//end __construct() + + /** + * The target a read's options name; an entity this app did not build is passed by its id. + * + * @param ObjectFindOptions $options The read's options. + * + * @return static The target, of the class the constructor is called on. + * + * @spec exclude Value object of the ObjectService::find() facade; read behaviour owned by object-interactions. + */ + public static function fromFindOptions(ObjectFindOptions $options): static { + $register = $options->register; + if ($register instanceof RegisterInterface && ($register instanceof Register) === false) { + $register = $register->getId(); + } + + $schema = $options->schema; + if ($schema instanceof SchemaInterface && ($schema instanceof Schema) === false) { + $schema = $schema->getId(); + } + + return new static(register: $register, schema: $schema); + }//end fromFindOptions() +}//end class diff --git a/hydra-gates/contracts/ObjectPatch.php b/hydra-gates/contracts/ObjectPatch.php new file mode 100644 index 000000000..3c7755752 --- /dev/null +++ b/hydra-gates/contracts/ObjectPatch.php @@ -0,0 +1,56 @@ + + * @copyright 2026 Conduction B.V. + * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12 + * + * @version GIT: + * + * @link https://www.OpenRegister.app + * + * @spec openspec/specs/object-lifecycle/spec.md + */ + +declare(strict_types=1); + +namespace OCA\OpenRegister\Contract; + +use OCP\IUser; + +/** + * One partial update: the object, the fields that change, where to find it and who acts. + * + * @spec openspec/specs/object-lifecycle/spec.md + */ +class ObjectPatch { + + /** + * Constructor. + * + * @param string $objectId The object's id or UUID, as the caller holds it. + * @param array $data The fields to merge onto the stored object. + * @param ObjectFindTarget $target The register and schema the caller named. + * @param IUser|null $currentUser Explicit acting user, or null for the session user. + * + * @phpstan-param array $data + * @psalm-param array $data + * + * @spec openspec/specs/object-lifecycle/spec.md + */ + public function __construct( + public readonly string $objectId, + public readonly array $data, + public readonly ObjectFindTarget $target=new ObjectFindTarget(), + public readonly ?IUser $currentUser=null, + ) { + }//end __construct() +}//end class diff --git a/hydra-gates/contracts/ObjectSaveOptions.php b/hydra-gates/contracts/ObjectSaveOptions.php new file mode 100644 index 000000000..7f1dd5d69 --- /dev/null +++ b/hydra-gates/contracts/ObjectSaveOptions.php @@ -0,0 +1,61 @@ + + * @copyright 2026 Conduction B.V. + * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12 + * + * @version GIT: + * + * @link https://www.OpenRegister.app + * + * @spec openspec/specs/object-lifecycle/spec.md + */ + +namespace OCA\OpenRegister\Contract; + +/** + * How one object save runs: where it goes, which object it updates, what the answer expands, + * the files that come with it, the save policy and on whose behalf it is written. + * + * No strict_types: callers pass request values through it as they did to saveObject(). + * + * @spec openspec/specs/object-lifecycle/spec.md + */ +class ObjectSaveOptions { + + /** + * Constructor. + * + * @param ObjectFindTarget $target The register and schema the object is saved in. + * @param string|null $uuid The UUID of the object to update, null to create or read it from the object. + * @param array|null $extend Properties to extend the rendered result with. + * @param array|null $uploadedFiles Uploaded files from multipart/form-data. + * @param SavePolicy $policy Events, validation, insert-only and duplicate-override choices. + * @param SaveActor $actor The acting user and the owner the row is stamped with. + * + * @phpstan-param array|null $extend + * @phpstan-param array|null $uploadedFiles + * @psalm-param array|null $extend + * @psalm-param array|null $uploadedFiles + * + * @spec openspec/specs/object-lifecycle/spec.md + */ + public function __construct( + public readonly ObjectFindTarget $target=new ObjectFindTarget(), + public readonly ?string $uuid=null, + public readonly ?array $extend=[], + public readonly ?array $uploadedFiles=null, + public readonly SavePolicy $policy=new SavePolicy(), + public readonly SaveActor $actor=new SaveActor(), + ) { + }//end __construct() +}//end class diff --git a/hydra-gates/contracts/ObjectServiceInterface.php b/hydra-gates/contracts/ObjectServiceInterface.php index a6a56a2e6..2e47961ec 100644 --- a/hydra-gates/contracts/ObjectServiceInterface.php +++ b/hydra-gates/contracts/ObjectServiceInterface.php @@ -106,6 +106,20 @@ * Returns are the entity INTERFACE, satisfied covariantly by the concrete * `ObjectEntity`. * + * The option and result values (`ObjectSaveOptions`, `BulkSaveOptions`, + * `ObjectFindOptions`, `ObjectDeletion`, `ObjectPatch`, `LockRequest`, + * `UnlockRequest`, `ObjectValidationVerdict`) are this namespace's own + * classes, so a consuming app needs nothing beyond this directory. The + * deprecated `Kernel\Contracts\Value\` names extend them: a consumer passing + * either is accepted, and `validateObject()` may return the old subclass, + * which is both. An implementation or test double must type these + * parameters with the names here (or wider); one still typed with the old + * Kernel names is narrower than this interface and fatals at class load. + * The two defaults (`saveObject()`, `saveObjects()`) still build the + * deprecated names, so a call that omits them, and a generated mock of this + * interface, passes exactly the value it passed before; they move to the + * published names with the consuming apps (task 7.3). + * * `saveObject()` takes `array`, not `array|ObjectEntityInterface`. The * implementation accepts `array|ObjectEntity`, and `array|ObjectEntity` is * NARROWER than `array|ObjectEntityInterface` -- so declaring the union here @@ -145,34 +159,22 @@ interface ObjectServiceInterface { /** * Persist an object, creating or updating it. * - * @param array $object The object to store. - * @param ?array $extend Relations to expand on the result. - * @param string|int|null $register Register id, UUID or slug. - * @param string|int|null $schema Schema id, UUID or slug. - * @param ?string $uuid The object UUID. - * @param bool $_rbac Apply register RBAC. - * @param bool $_multitenancy Apply organisation scoping. - * @param bool $silent Suppress events for this save. - * @param bool $_validation Validate against the schema. - * @param ?array $uploadedFiles Files uploaded alongside the object. - * @param ?IUser $currentUser Explicit acting user; null uses the session. - * @param bool $failIfExists Fail instead of updating when the object already exists. + * @param array $object The object to store. + * @param ObjectSaveOptions $options The register and schema (id, UUID or slug), the object + * UUID, the relations to expand on the result, the files + * uploaded alongside the object, the save policy (events, + * validation, insert-only) and the explicit acting user + * (null uses the session). + * @param bool $_rbac Apply register RBAC. + * @param bool $_multitenancy Apply organisation scoping. * * @return ObjectEntityInterface The stored object. */ public function saveObject( array $object, - ?array $extend=[], - string|int|null $register=null, - string|int|null $schema=null, - ?string $uuid=null, + ObjectSaveOptions $options=new \OCA\OpenRegister\Kernel\Contracts\Value\ObjectSaveOptions(), bool $_rbac=true, - bool $_multitenancy=true, - bool $silent=false, - bool $_validation=true, - ?array $uploadedFiles=null, - ?IUser $currentUser=null, - bool $failIfExists=false + bool $_multitenancy=true ): ObjectEntityInterface; /** @@ -187,28 +189,18 @@ public function setRegister(string|int $register): static; /** * Find a single object by id, UUID or slug. * - * @param int|string $id Object id, UUID or slug. - * @param ?array $_extend Relations to expand on the result. - * @param bool $files Include file metadata. - * @param string|int|null $register Register id, UUID or slug. - * @param string|int|null $schema Schema id, UUID or slug. - * @param bool $_rbac Apply register RBAC. - * @param bool $_multitenancy Apply organisation scoping. - * @param bool $_render Render the entity before returning it. - * @param bool $_audit Write an audit-trail entry. + * @param int|string $id Object id, UUID or slug. + * @param ObjectFindOptions|null $options Register, schema, extend, files, render and audit. + * @param bool $_rbac Apply register RBAC. + * @param bool $_multitenancy Apply organisation scoping. * * @return ?ObjectEntityInterface The object, or null when absent or not permitted. */ public function find( int|string $id, - ?array $_extend=[], - bool $files=false, - string|int|null $register=null, - string|int|null $schema=null, + ?ObjectFindOptions $options=null, bool $_rbac=true, - bool $_multitenancy=true, - bool $_render=true, - bool $_audit=true + bool $_multitenancy=true ): ?ObjectEntityInterface; /** @@ -259,26 +251,20 @@ public function searchObjects( /** * Delete an object by UUID. * - * @param string $uuid The object UUID. - * @param string|int|null $register Register id, UUID or slug. - * @param string|int|null $schema Schema id, UUID or slug. - * @param bool $_rbac Apply register RBAC. - * @param bool $_multitenancy Apply organisation scoping. - * @param bool $_retentionSweep Run as part of a retention sweep. - * @param ?IUser $currentUser Explicit acting user; null uses the session. - * @param bool $permanent Delete permanently instead of soft-deleting. + * @param ObjectDeletion $deletion The object UUID, the optional register and schema scope, + * the explicit acting user (null uses the session) and + * whether to delete permanently instead of soft-deleting. + * @param bool $_rbac Apply register RBAC. + * @param bool $_multitenancy Apply organisation scoping. + * @param bool $_retentionSweep Run as part of a retention sweep. * * @return bool True when the object was deleted. */ public function deleteObject( - string $uuid, - string|int|null $register=null, - string|int|null $schema=null, + ObjectDeletion $deletion, bool $_rbac=true, bool $_multitenancy=true, - bool $_retentionSweep=false, - ?IUser $currentUser=null, - bool $permanent=false + bool $_retentionSweep=false ): bool; /** @@ -354,30 +340,21 @@ public function buildSearchQuery( /** * Persist many objects in one bulk operation. * - * @param array $objects The objects to store. - * @param string|int|null $register Register id, UUID or slug. - * @param string|int|null $schema Schema id, UUID or slug. - * @param bool $_rbac Apply register RBAC. - * @param bool $_multitenancy Apply organisation scoping. - * @param bool $validation Validate against the schema. - * @param bool $events Emit events for each object. - * @param bool $deduplicateIds Drop duplicate ids within the batch. - * @param bool $enrich Enrich each object with derived metadata. - * @param bool $_audit Write an audit-trail entry. + * @param array $objects The objects to store. + * @param BulkSaveOptions $options The register and schema for rows that name none (id, UUID + * or slug), whether to validate against the schema, whether + * to emit events for each object, and whether to write + * audit-trail entries. + * @param bool $_rbac Apply register RBAC. + * @param bool $_multitenancy Apply organisation scoping. * * @return array The stored objects. */ public function saveObjects( array $objects, - string|int|null $register=null, - string|int|null $schema=null, + BulkSaveOptions $options=new \OCA\OpenRegister\Kernel\Contracts\Value\BulkSaveOptions(), bool $_rbac=true, - bool $_multitenancy=true, - bool $validation=false, - bool $events=false, - bool $deduplicateIds=true, - bool $enrich=true, - bool $_audit=true + bool $_multitenancy=true ): array; /** @@ -456,36 +433,24 @@ public function count(array $config=[]): int; /** * Release a lock on an object. * - * @param string|int $identifier The object id or UUID. - * @param bool $advisory Take an advisory (non-blocking) lock. - * @param ?string $runUuid The flow run releasing the lock, for a run-scoped lock. + * @param UnlockRequest $request The object, the advisory flag and the flow run releasing a run-scoped lock. + * A request with `break` set is refused; breakObjectLock() breaks a lock. * * @return bool True when the lock was released. */ - public function unlockObject(string|int $identifier, bool $advisory=false, ?string $runUuid=null): bool; + public function unlockObject(UnlockRequest $request): bool; /** * Take a lock on an object. * - * @param string $identifier The object id or UUID. - * @param ?string $process A label for the process holding the lock. - * @param ?int $duration Lock duration in seconds. - * @param bool $advisory Take an advisory (non-blocking) lock. - * @param ?string $runUuid The flow run taking the lock. A run-scoped lock - * refuses every other caller, the run's own runAs - * user included. - * @param ?string $nodeId The flow node that took it, recorded for the sweep. + * @param LockRequest $request The object, the process label, the duration in seconds and the flow + * run step taking the lock. A run-scoped lock refuses every other caller, + * the run's own runAs user included. + * @param bool $advisory Take an advisory (non-blocking) lock. * * @return array The resulting lock state. */ - public function lockObject( - string $identifier, - ?string $process=null, - ?int $duration=null, - bool $advisory=false, - ?string $runUuid=null, - ?string $nodeId=null - ): array; + public function lockObject(LockRequest $request, bool $advisory=false): array; /** * Delete many objects by UUID. @@ -539,8 +504,8 @@ public function getLogs( * * @param string $objectId The object UUID. * @param array $data The object's COMPLETE new data. Anything omitted is dropped. - * @param bool $_rbac Apply register RBAC. - * @param bool $_multitenancy Apply organisation scoping. + * @param bool $_rbac Apply register RBAC; false lifts it for this save, as with saveObject(). + * @param bool $_multitenancy Apply organisation scoping; false lifts it for this save, as with saveObject(). * * @return ObjectEntityInterface The replaced object. * @@ -571,15 +536,13 @@ public function updateObject( * The merged result goes through the same save path as `saveObject()`, so * schema validation, the audit trail and event dispatch all still apply. * - * @param string $objectId Object id, UUID or slug. - * @param array $data The partial data to merge. Omitted keys are PRESERVED. - * @param string|int|null $register Register id, UUID or slug. - * @param string|int|null $schema Schema id, UUID or slug. - * @param bool $_rbac Apply register RBAC. - * @param bool $_multitenancy Apply organisation scoping. - * @param ?IUser $currentUser Explicit acting user; null uses the session. - * Non-HTTP callers (cron, flow runs, imports) - * should pass one to avoid a default-deny. + * @param ObjectPatch $patch The object id, UUID or slug, the partial data to merge + * (omitted keys are PRESERVED), the optional register and + * schema scope, and the explicit acting user (null uses the + * session; non-HTTP callers such as cron, flow runs and + * imports should pass one to avoid a default-deny). + * @param bool $_rbac Apply register RBAC. + * @param bool $_multitenancy Apply organisation scoping. * * @return ObjectEntityInterface The patched object. * @@ -598,15 +561,7 @@ public function updateObject( * not on this merge, because leaf apps read it from vendor/: land those * three doubles before the release, or pin. */ - public function patchObject( - string $objectId, - array $data, - string|int|null $register=null, - string|int|null $schema=null, - bool $_rbac=true, - bool $_multitenancy=true, - ?IUser $currentUser=null - ): ObjectEntityInterface; + public function patchObject(ObjectPatch $patch, bool $_rbac=true, bool $_multitenancy=true): ObjectEntityInterface; /** * The objects this object refers to. @@ -655,22 +610,16 @@ public function findByRelations(string $search, bool $partialMatch=true): array; /** * Find an object without emitting audit or read events. * - * @param string $id Object id, UUID or slug. - * @param ?array $_extend Relations to expand on the result. - * @param bool $files Include file metadata. - * @param string|int|null $register Register id, UUID or slug. - * @param string|int|null $schema Schema id, UUID or slug. - * @param bool $_rbac Apply register RBAC. - * @param bool $_multitenancy Apply organisation scoping. + * @param string $id Object id, UUID or slug. + * @param ObjectFindOptions|null $options Register, schema, extend and files; render and audit are ignored. + * @param bool $_rbac Apply register RBAC. + * @param bool $_multitenancy Apply organisation scoping. * * @return ObjectEntityInterface The object. */ public function findSilent( string $id, - ?array $_extend=[], - bool $files=false, - string|int|null $register=null, - string|int|null $schema=null, + ?ObjectFindOptions $options=null, bool $_rbac=true, bool $_multitenancy=true ): ObjectEntityInterface; @@ -694,6 +643,26 @@ public function countSearchObjects( ?string $uses=null ): int; + /** + * Whether a sample record would be accepted, without saving it. + * + * Checks the sample against the schema and every save rule that decides + * acceptance (coded values, dependent values, unique fields, declared + * bounds, read-only fields), as a create, or with an id as an update of that + * object. Writes nothing and dispatches no object event. The sample is + * invalid exactly when a save of it would be refused for one of these rules. + * + * @param array $object The sample record. + * @param string|int $register The register (id, uuid or slug). + * @param string|int $schema The schema (id, uuid or slug). + * @param ?string $id The object the sample updates, or null for a create. + * + * @return ObjectValidationVerdict `valid`, and one error per refused property with the rule that refused it. + * + * @spec openspec/changes/records-validate-without-saving/specs/objects-crud/spec.md#requirement-a-record-can-be-validated-without-saving-it + */ + public function validateObject(array $object, string|int $register, string|int $schema, ?string $id=null): ObjectValidationVerdict; + /** * The object currently held as context, if any. * diff --git a/hydra-gates/contracts/ObjectValidationVerdict.php b/hydra-gates/contracts/ObjectValidationVerdict.php new file mode 100644 index 000000000..9246713b0 --- /dev/null +++ b/hydra-gates/contracts/ObjectValidationVerdict.php @@ -0,0 +1,78 @@ + + * @copyright 2026 Conduction B.V. + * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12 + * + * @version GIT: + * + * @link https://OpenRegister.app + * + * @spec openspec/changes/records-validate-without-saving/specs/objects-crud/spec.md#requirement-a-record-can-be-validated-without-saving-it + */ + +declare(strict_types=1); + +namespace OCA\OpenRegister\Contract; + +use JsonSerializable; + +/** + * The answer of a validate-only call: valid exactly when no rule refuses the + * sample, with one entry per refused property naming the rule. + * + * Rules: `schema` (the schema validator), `unique`, `field-type` (an extended + * field type), `write-rule` (declared bounds, repeating groups, geometry, + * read-only and lens rules, which name no single property), + * `coded-value`, `concept-shape`, `dependent-value`. A property of null + * means the refusal names no single property. + * + * @spec openspec/changes/records-validate-without-saving/specs/objects-crud/spec.md#requirement-a-record-can-be-validated-without-saving-it + */ +class ObjectValidationVerdict implements JsonSerializable { + + /** + * Constructor. + * + * @param array $errors The refusals. + * + * @return void + * + * @spec openspec/changes/records-validate-without-saving/specs/objects-crud/spec.md#requirement-a-record-can-be-validated-without-saving-it + */ + public function __construct( + public readonly array $errors=[], + ) { + }//end __construct() + + /** + * Whether the sample would be accepted. + * + * @return bool + * + * @spec openspec/changes/records-validate-without-saving/specs/objects-crud/spec.md#requirement-a-record-can-be-validated-without-saving-it + */ + public function isValid(): bool { + return $this->errors === []; + }//end isValid() + + /** + * The verdict as the API answers it. + * + * @return array{valid: bool, errors: array} + * + * @spec openspec/changes/records-validate-without-saving/specs/objects-crud/spec.md#requirement-a-record-can-be-validated-without-saving-it + */ + public function jsonSerialize(): array { + return ['valid' => $this->isValid(), 'errors' => $this->errors]; + }//end jsonSerialize() +}//end class diff --git a/hydra-gates/contracts/SaveActor.php b/hydra-gates/contracts/SaveActor.php new file mode 100644 index 000000000..fba618c21 --- /dev/null +++ b/hydra-gates/contracts/SaveActor.php @@ -0,0 +1,58 @@ + + * @copyright 2026 Conduction B.V. + * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12 + * + * @version GIT: + * + * @link https://www.OpenRegister.app + * + * @spec openspec/specs/object-lifecycle/spec.md + */ + +namespace OCA\OpenRegister\Contract; + +use OCP\IUser; + +/** + * On whose behalf one object save is written, and who owns a row it creates. + * + * @spec openspec/specs/object-lifecycle/spec.md + */ +class SaveActor { + + /** + * Constructor. + * + * @param IUser|null $currentUser Explicit acting user for `@self.folder` access checks; null resolves + * `IUserSession::getUser()`. Non-HTTP callers (cron, import pipelines, + * event listeners) MUST pass one to avoid the default-deny fall-through + * on every folder-bound save. + * @param string|null $owner An explicit owner for a NEW object (a draft's scope value such as + * `portal:`, decision 195). Service-level only: no controller + * forwards it. An update keeps the stored owner. + * @param bool $unowned Stamp the SYSTEM identity as owner even when a user session exists, for + * a genuinely anonymous write (a citizen submitting a public form). No + * controller forwards it, so no REST request can ask to be anonymised. + * + * @SuppressWarnings(PHPMD.BooleanArgumentFlag) Attributed writes are the default. + * + * @spec openspec/specs/object-lifecycle/spec.md + */ + public function __construct( + public readonly ?IUser $currentUser=null, + public readonly ?string $owner=null, + public readonly bool $unowned=false, + ) { + }//end __construct() +}//end class diff --git a/hydra-gates/contracts/SavePolicy.php b/hydra-gates/contracts/SavePolicy.php new file mode 100644 index 000000000..3446ccce9 --- /dev/null +++ b/hydra-gates/contracts/SavePolicy.php @@ -0,0 +1,55 @@ + + * @copyright 2026 Conduction B.V. + * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12 + * + * @version GIT: + * + * @link https://www.OpenRegister.app + * + * @spec openspec/specs/object-lifecycle/spec.md + */ + +namespace OCA\OpenRegister\Contract; + +/** + * The policy switches of one object save. Every default is the behaviour a caller gets without asking. + * + * @spec openspec/specs/object-lifecycle/spec.md + */ +class SavePolicy { + + /** + * Constructor. + * + * @param bool $silent Skip audit trail creation and events. + * @param bool $validation Validate the object against its schema. A bulk importer with + * pre-validated rows may decline re-validating every one of them. + * @param bool $failIfExists Insert-only: throw ObjectExistsException rather than update when the + * identifier is taken. False is an upsert. + * @param bool $dedupOverride Save through a blocking duplicate match, when the caller is entitled to. + * ObjectsController reads it from the raw request, because the body filter + * there strips `_`-prefixed keys. + * + * @SuppressWarnings(PHPMD.BooleanArgumentFlag) Each flag is a documented save policy with a safe default. + * + * @spec openspec/specs/object-lifecycle/spec.md + */ + public function __construct( + public readonly bool $silent=false, + public readonly bool $validation=true, + public readonly bool $failIfExists=false, + public readonly bool $dedupOverride=false, + ) { + }//end __construct() +}//end class diff --git a/hydra-gates/contracts/UnlockRequest.php b/hydra-gates/contracts/UnlockRequest.php new file mode 100644 index 000000000..6a6a05b3d --- /dev/null +++ b/hydra-gates/contracts/UnlockRequest.php @@ -0,0 +1,49 @@ + + * @copyright 2026 Conduction B.V. + * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12 + * + * @version GIT: + * + * @link https://OpenRegister.app + * + * @spec openspec/changes/run-scoped-object-locking/specs/run-scoped-object-locking/spec.md#requirement-a-lock-is-released-through-its-own-endpoint-and-a-release-says-whether-there-was-one + */ + +declare(strict_types=1); + +namespace OCA\OpenRegister\Contract; + +/** + * The object, the kind of lock and who releases it. + * + * @spec openspec/changes/run-scoped-object-locking/specs/run-scoped-object-locking/spec.md#requirement-a-lock-is-released-through-its-own-endpoint-and-a-release-says-whether-there-was-one + */ +class UnlockRequest { + + /** + * Constructor. + * + * @param string $identifier Object ID or UUID (or the advisory key). + * @param bool $advisory Release a pre-creation advisory lock without a lookup. + * @param string|null $runUuid Flow run releasing the lock, for a run-scoped lock. + * @param bool $break Release regardless of holder; authorized at the call site. + */ + public function __construct( + public readonly string $identifier, + public readonly bool $advisory=false, + public readonly ?string $runUuid=null, + public readonly bool $break=false, + ) { + }//end __construct() +}//end class