Initial Version
This commit is contained in:
root
333
shared/lib/Files/Service/IServiceBase.php
Normal file
333
shared/lib/Files/Service/IServiceBase.php
Normal file
@@ -0,0 +1,333 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
/**
|
||||
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
|
||||
* SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
*/
|
||||
|
||||
namespace KTXF\Files\Service;
|
||||
|
||||
use JsonSerializable;
|
||||
use KTXF\Files\Node\INodeBase;
|
||||
use KTXF\Files\Node\INodeCollectionBase;
|
||||
use KTXF\Files\Node\INodeEntityBase;
|
||||
use KTXF\Resource\Filter\IFilter;
|
||||
use KTXF\Resource\Range\IRange;
|
||||
use KTXF\Resource\Range\RangeType;
|
||||
use KTXF\Resource\Sort\ISort;
|
||||
|
||||
interface IServiceBase extends JsonSerializable {
|
||||
|
||||
// Collection Capabilities
|
||||
public const CAPABILITY_COLLECTION_LIST = 'CollectionList';
|
||||
public const CAPABILITY_COLLECTION_LIST_FILTER = 'CollectionListFilter';
|
||||
public const CAPABILITY_COLLECTION_LIST_SORT = 'CollectionListSort';
|
||||
public const CAPABILITY_COLLECTION_EXTANT = 'CollectionExtant';
|
||||
public const CAPABILITY_COLLECTION_FETCH = 'CollectionFetch';
|
||||
|
||||
// Entity Capabilities
|
||||
public const CAPABILITY_ENTITY_LIST = 'EntityList';
|
||||
public const CAPABILITY_ENTITY_LIST_FILTER = 'EntityListFilter';
|
||||
public const CAPABILITY_ENTITY_LIST_SORT = 'EntityListSort';
|
||||
public const CAPABILITY_ENTITY_LIST_RANGE = 'EntityListRange';
|
||||
public const CAPABILITY_ENTITY_DELTA = 'EntityDelta';
|
||||
public const CAPABILITY_ENTITY_EXTANT = 'EntityExtant';
|
||||
public const CAPABILITY_ENTITY_FETCH = 'EntityFetch';
|
||||
public const CAPABILITY_ENTITY_READ = 'EntityRead';
|
||||
public const CAPABILITY_ENTITY_READ_STREAM = 'EntityReadStream';
|
||||
public const CAPABILITY_ENTITY_READ_CHUNK = 'EntityReadChunk';
|
||||
|
||||
// Node Capabilities (recursive/unified)
|
||||
public const CAPABILITY_NODE_LIST = 'NodeList';
|
||||
public const CAPABILITY_NODE_LIST_FILTER = 'NodeListFilter';
|
||||
public const CAPABILITY_NODE_LIST_SORT = 'NodeListSort';
|
||||
public const CAPABILITY_NODE_LIST_RANGE = 'NodeListRange';
|
||||
public const CAPABILITY_NODE_DELTA = 'NodeDelta';
|
||||
|
||||
// JSON Constants
|
||||
public const JSON_TYPE = 'files.service';
|
||||
public const JSON_PROPERTY_TYPE = '@type';
|
||||
public const JSON_PROPERTY_PROVIDER = 'provider';
|
||||
public const JSON_PROPERTY_ID = 'id';
|
||||
public const JSON_PROPERTY_LABEL = 'label';
|
||||
public const JSON_PROPERTY_CAPABILITIES = 'capabilities';
|
||||
public const JSON_PROPERTY_ENABLED = 'enabled';
|
||||
|
||||
/**
|
||||
* Confirms if specific capability is supported
|
||||
*
|
||||
* @since 2025.11.01
|
||||
*
|
||||
* @param string $value required ability e.g. 'EntityList'
|
||||
*
|
||||
* @return bool
|
||||
*/
|
||||
public function capable(string $value): bool;
|
||||
|
||||
/**
|
||||
* Lists all supported capabilities
|
||||
*
|
||||
* @since 2025.11.01
|
||||
*
|
||||
* @return array<string,bool>
|
||||
*/
|
||||
public function capabilities(): array;
|
||||
|
||||
/**
|
||||
* Unique identifier of the provider this service belongs to
|
||||
*
|
||||
* @since 2025.11.01
|
||||
*/
|
||||
public function in(): string;
|
||||
|
||||
/**
|
||||
* Unique arbitrary text string identifying this service (e.g. 1 or service1 or anything else)
|
||||
*
|
||||
* @since 2025.11.01
|
||||
*/
|
||||
public function id(): string|int;
|
||||
|
||||
/**
|
||||
* Gets the localized human friendly name of this service (e.g. ACME Company File Service)
|
||||
*
|
||||
* @since 2025.11.01
|
||||
*/
|
||||
public function getLabel(): string;
|
||||
|
||||
/**
|
||||
* Gets the active status of this service
|
||||
*
|
||||
* @since 2025.11.01
|
||||
*/
|
||||
public function getEnabled(): bool;
|
||||
|
||||
// ==================== Collection Methods ====================
|
||||
|
||||
/**
|
||||
* List of accessible collections at a specific location
|
||||
*
|
||||
* @since 2025.11.01
|
||||
*
|
||||
* @param string|int|null $location Parent collection identifier, null for root
|
||||
*
|
||||
* @return array<string|int,INodeCollectionBase>
|
||||
*/
|
||||
public function collectionList(string|int|null $location = null, ?IFilter $filter = null, ?ISort $sort = null): array;
|
||||
|
||||
/**
|
||||
* Fresh filter for collection list
|
||||
*
|
||||
* @since 2025.11.01
|
||||
*/
|
||||
public function collectionListFilter(): IFilter;
|
||||
|
||||
/**
|
||||
* Fresh sort for collection list
|
||||
*
|
||||
* @since 2025.11.01
|
||||
*/
|
||||
public function collectionListSort(): ISort;
|
||||
|
||||
/**
|
||||
* Confirms if specific collection exists
|
||||
*
|
||||
* @since 2025.11.01
|
||||
*
|
||||
* @param string|int|null $identifier Collection identifier
|
||||
*/
|
||||
public function collectionExtant(string|int|null $identifier): bool;
|
||||
|
||||
/**
|
||||
* Fetches details about a specific collection
|
||||
*
|
||||
* @since 2025.11.01
|
||||
*
|
||||
* @param string|int|null $identifier Collection identifier
|
||||
*/
|
||||
public function collectionFetch(string|int|null $identifier): ?INodeCollectionBase;
|
||||
|
||||
// ==================== Entity Methods ====================
|
||||
|
||||
/**
|
||||
* Lists all entities in a specific collection
|
||||
*
|
||||
* @since 2025.11.01
|
||||
*
|
||||
* @param string|int|null $collection Collection identifier
|
||||
*
|
||||
* @return array<string|int,INodeEntityBase>
|
||||
*/
|
||||
public function entityList(string|int|null $collection, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null): array;
|
||||
|
||||
/**
|
||||
* Fresh filter for entity list
|
||||
*
|
||||
* @since 2025.11.01
|
||||
*/
|
||||
public function entityListFilter(): IFilter;
|
||||
|
||||
/**
|
||||
* Fresh sort for entity list
|
||||
*
|
||||
* @since 2025.11.01
|
||||
*/
|
||||
public function entityListSort(): ISort;
|
||||
|
||||
/**
|
||||
* Fresh range for entity list
|
||||
*
|
||||
* @since 2025.11.01
|
||||
*/
|
||||
public function entityListRange(RangeType $type): IRange;
|
||||
|
||||
/**
|
||||
* Lists all changes from a specific signature
|
||||
*
|
||||
* @since 2025.11.01
|
||||
*
|
||||
* @param string|int|null $collection Collection identifier
|
||||
* @param string $signature Sync token signature
|
||||
* @param string $detail Detail level: ids | meta | full
|
||||
*
|
||||
* @return array{
|
||||
* added: array<string|int>,
|
||||
* updated: array<string|int>,
|
||||
* deleted: array<string|int>,
|
||||
* signature: string
|
||||
* }
|
||||
*/
|
||||
public function entityDelta(string|int|null $collection, string $signature, string $detail = 'ids'): array;
|
||||
|
||||
/**
|
||||
* Confirms if specific entities exist in a collection
|
||||
*
|
||||
* @since 2025.11.01
|
||||
*
|
||||
* @param string|int|null $collection Collection identifier
|
||||
* @param string|int ...$identifiers Entity identifiers
|
||||
*
|
||||
* @return array<string|int,bool>
|
||||
*/
|
||||
public function entityExtant(string|int|null $collection, string|int ...$identifiers): array;
|
||||
|
||||
/**
|
||||
* Fetches details about specific entities in a collection
|
||||
*
|
||||
* @since 2025.11.01
|
||||
*
|
||||
* @param string|int|null $collection Collection identifier
|
||||
* @param string|int ...$identifiers Entity identifiers
|
||||
*
|
||||
* @return array<string|int,INodeEntityBase>
|
||||
*/
|
||||
public function entityFetch(string|int|null $collection, string|int ...$identifiers): array;
|
||||
|
||||
/**
|
||||
* Reads the entire content of an entity as a string
|
||||
*
|
||||
* @since 2025.11.01
|
||||
*
|
||||
* @param string|int|null $collection Collection identifier
|
||||
* @param string|int $identifier Entity identifier
|
||||
*
|
||||
* @return string|null File content or null if not found
|
||||
*
|
||||
* @throws \KTXF\Resource\Exceptions\InvalidArgumentException
|
||||
* @throws \KTXF\Resource\Exceptions\UnsupportedException
|
||||
* @throws \KTXF\Resource\Exceptions\UnauthorizedException
|
||||
*/
|
||||
public function entityRead(string|int|null $collection, string|int $identifier): ?string;
|
||||
|
||||
/**
|
||||
* Opens a stream to read the content of an entity
|
||||
*
|
||||
* @since 2025.11.01
|
||||
*
|
||||
* @param string|int|null $collection Collection identifier
|
||||
* @param string|int $identifier Entity identifier
|
||||
*
|
||||
* @return resource|null Stream resource or null if not found
|
||||
*
|
||||
* @throws \KTXF\Resource\Exceptions\InvalidArgumentException
|
||||
* @throws \KTXF\Resource\Exceptions\UnsupportedException
|
||||
* @throws \KTXF\Resource\Exceptions\UnauthorizedException
|
||||
*/
|
||||
public function entityReadStream(string|int|null $collection, string|int $identifier);
|
||||
|
||||
/**
|
||||
* Reads a chunk of content from an entity
|
||||
*
|
||||
* @since 2025.11.01
|
||||
*
|
||||
* @param string|int|null $collection Collection identifier
|
||||
* @param string|int $identifier Entity identifier
|
||||
* @param int $offset Starting byte position (0-indexed)
|
||||
* @param int $length Number of bytes to read
|
||||
*
|
||||
* @return string|null Chunk content or null if not found
|
||||
*
|
||||
* @throws \KTXF\Resource\Exceptions\InvalidArgumentException
|
||||
* @throws \KTXF\Resource\Exceptions\UnsupportedException
|
||||
* @throws \KTXF\Resource\Exceptions\UnauthorizedException
|
||||
*/
|
||||
public function entityReadChunk(string|int|null $collection, string|int $identifier, int $offset, int $length): ?string;
|
||||
|
||||
// ==================== Node Methods (Recursive/Unified) ====================
|
||||
|
||||
/**
|
||||
* Lists all nodes (collections and entities) at a location, optionally recursive
|
||||
* Returns a flat list with parent references via in()
|
||||
*
|
||||
* @since 2025.11.01
|
||||
*
|
||||
* @param string|int|null $location Starting location, null for root
|
||||
* @param bool $recursive Whether to list recursively
|
||||
*
|
||||
* @return array<string|int,INodeBase>
|
||||
*/
|
||||
public function nodeList(string|int|null $location = null, bool $recursive = false, ?IFilter $filter = null, ?ISort $sort = null, ?IRange $range = null): array;
|
||||
|
||||
/**
|
||||
* Fresh filter for node list
|
||||
*
|
||||
* @since 2025.11.01
|
||||
*/
|
||||
public function nodeListFilter(): IFilter;
|
||||
|
||||
/**
|
||||
* Fresh sort for node list
|
||||
*
|
||||
* @since 2025.11.01
|
||||
*/
|
||||
public function nodeListSort(): ISort;
|
||||
|
||||
/**
|
||||
* Fresh range for node list
|
||||
*
|
||||
* @since 2025.11.01
|
||||
*/
|
||||
public function nodeListRange(RangeType $type): IRange;
|
||||
|
||||
/**
|
||||
* Lists all node changes from a specific signature, optionally recursive
|
||||
* Returns flat list with parent references
|
||||
*
|
||||
* @since 2025.11.01
|
||||
*
|
||||
* @param string|int|null $location Starting location, null for root
|
||||
* @param string $signature Sync token signature
|
||||
* @param bool $recursive Whether to include recursive changes
|
||||
* @param string $detail Detail level: ids | meta | full
|
||||
*
|
||||
* @return array{
|
||||
* added: array<string|int,INodeBase>|array<string|int>,
|
||||
* updated: array<string|int,INodeBase>|array<string|int>,
|
||||
* deleted: array<string|int>,
|
||||
* signature: string
|
||||
* }
|
||||
*/
|
||||
public function nodeDelta(string|int|null $location, string $signature, bool $recursive = false, string $detail = 'ids'): array;
|
||||
|
||||
}
|
||||
Reference in New Issue
Block a user