Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 43 additions & 1 deletion hydra-gates/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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\<Name>`, 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
Expand All @@ -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';
Expand Down Expand Up @@ -277,6 +305,20 @@ the autoloader is precisely the defect this change removed.
<file name="vendor/conduction/hydra-gates/hydra-gates/contracts/RegisterSlugResolverInterface.php" />
<file name="vendor/conduction/hydra-gates/hydra-gates/contracts/RegisterSlugResolution.php" />
<file name="vendor/conduction/hydra-gates/hydra-gates/contracts/EmailLinkReaderInterface.php" />
<file name="vendor/conduction/hydra-gates/hydra-gates/contracts/ObjectFileReaderInterface.php" />
<file name="vendor/conduction/hydra-gates/hydra-gates/contracts/ObjectFindTarget.php" />
<file name="vendor/conduction/hydra-gates/hydra-gates/contracts/SaveActor.php" />
<file name="vendor/conduction/hydra-gates/hydra-gates/contracts/SavePolicy.php" />
<file name="vendor/conduction/hydra-gates/hydra-gates/contracts/BulkBatchDefaults.php" />
<file name="vendor/conduction/hydra-gates/hydra-gates/contracts/LockRunStep.php" />
<file name="vendor/conduction/hydra-gates/hydra-gates/contracts/ObjectSaveOptions.php" />
<file name="vendor/conduction/hydra-gates/hydra-gates/contracts/BulkSaveOptions.php" />
<file name="vendor/conduction/hydra-gates/hydra-gates/contracts/LockRequest.php" />
<file name="vendor/conduction/hydra-gates/hydra-gates/contracts/UnlockRequest.php" />
<file name="vendor/conduction/hydra-gates/hydra-gates/contracts/ObjectFindOptions.php" />
<file name="vendor/conduction/hydra-gates/hydra-gates/contracts/ObjectDeletion.php" />
<file name="vendor/conduction/hydra-gates/hydra-gates/contracts/ObjectPatch.php" />
<file name="vendor/conduction/hydra-gates/hydra-gates/contracts/ObjectValidationVerdict.php" />
</stubs>
```

Expand Down
48 changes: 48 additions & 0 deletions hydra-gates/contracts/BulkBatchDefaults.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
<?php

/**
* BulkBatchDefaults
*
* The register and schema a bulk save names for every row that names none.
*
* SPDX-License-Identifier: EUPL-1.2
* SPDX-FileCopyrightText: 2026 Conduction B.V.
*
* @category Contract
* @package OCA\OpenRegister\Contract
*
* @author Conduction Development Team <dev@conduction.nl>
* @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
52 changes: 52 additions & 0 deletions hydra-gates/contracts/BulkSaveOptions.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
<?php

/**
* BulkSaveOptions
*
* The per-call switches of one bulk save: its default register and schema, and whether
* it validates, dispatches events and writes audit rows.
*
* SPDX-License-Identifier: EUPL-1.2
* SPDX-FileCopyrightText: 2026 Conduction B.V.
*
* @category Contract
* @package OCA\OpenRegister\Contract
*
* @author Conduction Development Team <dev@conduction.nl>
* @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
64 changes: 64 additions & 0 deletions hydra-gates/contracts/LockRequest.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
<?php

/**
* LockRequest: what a caller asks for when it takes an object lock.
*
* SPDX-License-Identifier: EUPL-1.2
* SPDX-FileCopyrightText: 2026 Conduction B.V.
*
* @category Contract
* @package OCA\OpenRegister\Contract
*
* @author Conduction Development Team <dev@conduction.nl>
* @copyright 2026 Conduction B.V.
* @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
*
* @version GIT: <git-id>
*
* @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
45 changes: 45 additions & 0 deletions hydra-gates/contracts/LockRunStep.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
<?php

/**
* LockRunStep: the flow run and node that take a run-scoped object lock.
*
* SPDX-License-Identifier: EUPL-1.2
* SPDX-FileCopyrightText: 2026 Conduction B.V.
*
* @category Contract
* @package OCA\OpenRegister\Contract
*
* @author Conduction Development Team <dev@conduction.nl>
* @copyright 2026 Conduction B.V.
* @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
*
* @version GIT: <git-id>
*
* @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
76 changes: 76 additions & 0 deletions hydra-gates/contracts/ObjectDeletion.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
<?php

/**
* OpenRegister ObjectDeletion
*
* SPDX-License-Identifier: EUPL-1.2
* SPDX-FileCopyrightText: 2026 Conduction B.V.
*
* @category Contract
* @package OCA\OpenRegister\Contract
*
* @author Conduction Development Team <info@conduction.nl>
* @copyright 2026 Conduction B.V.
* @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
*
* @version GIT: <git_id>
*
* @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
Loading
Loading