Skip to content
Closed
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
6 changes: 4 additions & 2 deletions lib/Controller/DrcController.php
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,8 @@
use OCA\Dossiq\Service\Zgw\ZtcHelperFactory;
use OCA\Dossiq\Service\Zgw\ZgwSearchScope;
use OCA\Dossiq\Support\MapsZgwRows;
use OCA\OpenRegister\Kernel\Contracts\Value\LockRequest;
use OCA\OpenRegister\Kernel\Contracts\Value\UnlockRequest;
use OCP\AppFramework\Http;
use OCP\AppFramework\Http\Attribute\AnonRateLimit;
use OCP\AppFramework\Http\DataDownloadResponse;
Expand Down Expand Up @@ -1056,7 +1058,7 @@ private function alreadyLockedResponse(): JSONResponse {
* @throws \Throwable When OpenRegister refuses or fails the lock.
*/
private function lockWithNewLockId(object $objectService, ?array $mappingConfig, string $uuid): JSONResponse {
$objectService->lockObject(identifier: $uuid);
$objectService->lockObject(request: new LockRequest(identifier: $uuid));

// OpenRegister's lock system doesn't produce a ZGW lockId.
// Generate one and store it in the data blob for verification.
Expand Down Expand Up @@ -1263,7 +1265,7 @@ private function unlockRefusal(object $objectService, ?array $mappingConfig, str
* @throws \Throwable When OpenRegister fails the unlock.
*/
private function unlockAndClearLockId(object $objectService, ?array $mappingConfig, string $uuid): JSONResponse {
$objectService->unlockObject(identifier: $uuid);
$objectService->unlockObject(request: new UnlockRequest(identifier: $uuid));

// Clear lockId from the data blob.
if ($mappingConfig !== null) {
Expand Down
27 changes: 7 additions & 20 deletions tests/Stubs/Contract/ObjectServiceInterface.php
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,8 @@

namespace OCA\OpenRegister\Contract;

use OCA\OpenRegister\Kernel\Contracts\Value\LockRequest;
use OCA\OpenRegister\Kernel\Contracts\Value\UnlockRequest;
use OCP\IUser;

/**
Expand Down Expand Up @@ -412,36 +414,21 @@ 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, and whether the lock is advisory, run-scoped or broken.
*
* @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 holding process, the duration and the flow run and node.
* @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.
Expand Down
63 changes: 63 additions & 0 deletions tests/Stubs/Kernel/Contracts/Value/LockRequest.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
<?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 Service
* @package OCA\OpenRegister\Service\Object
*
* @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\Kernel\Contracts\Value;

/**
* The arguments of LockHandler::lock(), carried together through its steps.
*/
final 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 tests/Stubs/Kernel/Contracts/Value/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 Service
* @package OCA\OpenRegister\Service\Object
*
* @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\Kernel\Contracts\Value;

/**
* Which flow run took a lock, and from which node, as LockHandler::lock() was told.
*
* @spec openspec/specs/object-interactions/spec.md
*/
final 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
49 changes: 49 additions & 0 deletions tests/Stubs/Kernel/Contracts/Value/UnlockRequest.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
<?php

/**
* UnlockRequest: what a caller asks for when it releases an object lock.
*
* SPDX-License-Identifier: EUPL-1.2
* SPDX-FileCopyrightText: 2026 Conduction B.V.
*
* @category Service
* @package OCA\OpenRegister\Service\Object
*
* @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/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\Kernel\Contracts\Value;

/**
* 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
*/
final 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
5 changes: 3 additions & 2 deletions tests/Unit/Controller/DrcControllerContractTest.php
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@

use OCA\Dossiq\Controller\DrcController;
use OCA\Dossiq\Service\ZgwService;
use OCA\OpenRegister\Kernel\Contracts\Value\UnlockRequest;
use OCP\AppFramework\Http;
use OCP\AppFramework\Http\JSONResponse;
use OCP\IL10N;
Expand Down Expand Up @@ -89,7 +90,7 @@ public function saveObject(string $register, string $schema, array $object, ?str
*
* @return mixed The unlocked object row.
*/
public function unlockObject(string $identifier): mixed;
public function unlockObject(UnlockRequest $request): mixed;
}//end interface

/**
Expand Down Expand Up @@ -363,7 +364,7 @@ public function testUnlockWithTheMatchingLockIdClearsTheLockAndAnswers204(): voi
$objectService->method('find')->willReturn(['lockId' => 'the-real-lock', 'locked' => true]);
$objectService->expects($this->once())
->method('unlockObject')
->with('doc-1')
->with($this->callback(static fn (UnlockRequest $request): bool => $request->identifier === 'doc-1'))
->willReturn(['id' => 'doc-1']);
$objectService->method('saveObject')->willReturnCallback(
static function (
Expand Down
7 changes: 4 additions & 3 deletions tests/Unit/Controller/DrcDownloadLockContractTest.php
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@
use OCA\Dossiq\Service\ZgwDocumentService;
use OCA\Dossiq\Service\ZgwMappingService;
use OCA\Dossiq\Service\ZgwService;
use OCA\OpenRegister\Kernel\Contracts\Value\LockRequest;
use OCP\AppFramework\Http;
use OCP\AppFramework\Http\JSONResponse;
use OCP\IL10N;
Expand Down Expand Up @@ -97,7 +98,7 @@ public function saveObject(string $register, string $schema, array $object, ?str
*
* @return mixed The locked object row.
*/
public function lockObject(string $identifier): mixed;
public function lockObject(LockRequest $request): mixed;
}//end interface

/**
Expand Down Expand Up @@ -363,8 +364,8 @@ public function testLockTakesTheLockAndPersistsTheGeneratedLockIdItReturns(): vo
$objectService->expects($this->once())
->method('lockObject')
->willReturnCallback(
static function (string $identifier): array {
return ['id' => $identifier];
static function (LockRequest $request): array {
return ['id' => $request->identifier];
}
);
$objectService->expects($this->once())
Expand Down