Initial Version

2025-12-21 10:09:54 -05:00
commit 4ae6befc7b
422 changed files with 47225 additions and 0 deletions
--- a/shared/lib/Files/Service/IServiceBase.php
+++ b/shared/lib/Files/Service/IServiceBase.php
@@ -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;
+
+}
--- a/shared/lib/Files/Service/IServiceCollectionMutable.php
+++ b/shared/lib/Files/Service/IServiceCollectionMutable.php
@@ -0,0 +1,100 @@
+<?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 KTXF\Files\Node\INodeCollectionBase;
+use KTXF\Files\Node\INodeCollectionMutable;
+
+interface IServiceCollectionMutable extends IServiceBase {
+
+	public const CAPABILITY_COLLECTION_CREATE = 'CollectionCreate';
+	public const CAPABILITY_COLLECTION_MODIFY = 'CollectionModify';
+	public const CAPABILITY_COLLECTION_DESTROY = 'CollectionDestroy';
+	public const CAPABILITY_COLLECTION_COPY = 'CollectionCopy';
+	public const CAPABILITY_COLLECTION_MOVE = 'CollectionMove';
+
+	/**
+	 * Creates a new, empty collection node
+	 *
+	 * @since 2025.11.01
+	 */
+	public function collectionFresh(): INodeCollectionMutable;
+
+	/**
+	 * Creates a new collection at the specified location
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int|null $location Parent collection, null for root
+	 * @param INodeCollectionMutable $collection The collection to create
+	 * @param array $options Additional options
+	 *
+	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
+	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
+	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
+	 */
+	public function collectionCreate(string|int|null $location, INodeCollectionMutable $collection, array $options = []): INodeCollectionBase;
+
+	/**
+	 * Modifies an existing collection
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int $identifier Collection identifier
+	 * @param INodeCollectionMutable $collection The collection with modifications
+	 *
+	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
+	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
+	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
+	 */
+	public function collectionModify(string|int $identifier, INodeCollectionMutable $collection): INodeCollectionBase;
+
+	/**
+	 * Destroys an existing collection
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int $identifier Collection identifier
+	 *
+	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
+	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
+	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
+	 */
+	public function collectionDestroy(string|int $identifier): bool;
+
+	/**
+	 * Copies an existing collection to a new location
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int $identifier Collection identifier
+	 * @param string|int|null $location Destination parent collection, null for root
+	 *
+	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
+	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
+	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
+	 */
+	public function collectionCopy(string|int $identifier, string|int|null $location): INodeCollectionBase;
+
+	/**
+	 * Moves an existing collection to a new location
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int $identifier Collection identifier
+	 * @param string|int|null $location Destination parent collection, null for root
+	 *
+	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
+	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
+	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
+	 */
+	public function collectionMove(string|int $identifier, string|int|null $location): INodeCollectionBase;
+
+}
--- a/shared/lib/Files/Service/IServiceEntityMutable.php
+++ b/shared/lib/Files/Service/IServiceEntityMutable.php
@@ -0,0 +1,158 @@
+<?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 KTXF\Files\Node\INodeEntityBase;
+use KTXF\Files\Node\INodeEntityMutable;
+
+interface IServiceEntityMutable extends IServiceBase {
+
+	public const CAPABILITY_ENTITY_CREATE = 'EntityCreate';
+	public const CAPABILITY_ENTITY_MODIFY = 'EntityModify';
+	public const CAPABILITY_ENTITY_DESTROY = 'EntityDestroy';
+	public const CAPABILITY_ENTITY_COPY = 'EntityCopy';
+	public const CAPABILITY_ENTITY_MOVE = 'EntityMove';
+	public const CAPABILITY_ENTITY_WRITE = 'EntityWrite';
+	public const CAPABILITY_ENTITY_WRITE_STREAM = 'EntityWriteStream';
+	public const CAPABILITY_ENTITY_WRITE_CHUNK = 'EntityWriteChunk';
+
+	/**
+	 * Creates a new, empty entity node
+	 *
+	 * @since 2025.11.01
+	 */
+	public function entityFresh(): INodeEntityMutable;
+
+	/**
+	 * Creates a new entity in the specified collection
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int|null $collection Collection identifier, null for root
+	 * @param INodeEntityMutable $entity The entity to create
+	 * @param array $options Additional options
+	 *
+	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
+	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
+	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
+	 */
+	public function entityCreate(string|int|null $collection, INodeEntityMutable $entity, array $options = []): INodeEntityBase;
+
+	/**
+	 * Modifies an existing entity in the specified collection
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int|null $collection Collection identifier
+	 * @param string|int $identifier Entity identifier
+	 * @param INodeEntityMutable $entity The entity with modifications
+	 *
+	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
+	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
+	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
+	 */
+	public function entityModify(string|int|null $collection, string|int $identifier, INodeEntityMutable $entity): INodeEntityBase;
+
+	/**
+	 * Destroys an existing entity in the specified collection
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int|null $collection Collection identifier
+	 * @param string|int $identifier Entity identifier
+	 *
+	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
+	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
+	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
+	 */
+	public function entityDestroy(string|int|null $collection, string|int $identifier): bool;
+
+	/**
+	 * Copies an existing entity to a new collection
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int|null $collection Source collection identifier
+	 * @param string|int $identifier Entity identifier
+	 * @param string|int|null $destination Destination collection identifier, null for root
+	 *
+	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
+	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
+	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
+	 */
+	public function entityCopy(string|int|null $collection, string|int $identifier, string|int|null $destination): INodeEntityBase;
+
+	/**
+	 * Moves an existing entity to a new collection
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int|null $collection Source collection identifier
+	 * @param string|int $identifier Entity identifier
+	 * @param string|int|null $destination Destination collection identifier, null for root
+	 *
+	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
+	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
+	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
+	 */
+	public function entityMove(string|int|null $collection, string|int $identifier, string|int|null $destination): INodeEntityBase;
+
+	/**
+	 * Writes the entire content of an entity from a string
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int|null $collection Collection identifier
+	 * @param string|int $identifier Entity identifier
+	 * @param string $data Content to write
+	 *
+	 * @return int Number of bytes written
+	 *
+	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
+	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
+	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
+	 */
+	public function entityWrite(string|int|null $collection, string|int $identifier, string $data): int;
+
+	/**
+	 * Opens a stream to write the content of an entity
+	 *
+	 * @since 2025.11.01
+	 *
+	 * @param string|int|null $collection Collection identifier
+	 * @param string|int $identifier Entity identifier
+	 *
+	 * @return resource Stream resource for writing
+	 *
+	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
+	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
+	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
+	 */
+	public function entityWriteStream(string|int|null $collection, string|int $identifier);
+
+	/**
+	 * Writes a chunk of content to an entity at a specific position
+	 *
+	 * @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 string $data Chunk content to write
+	 *
+	 * @return int Number of bytes written
+	 *
+	 * @throws \KTXF\Resource\Exceptions\InvalidArgumentException
+	 * @throws \KTXF\Resource\Exceptions\UnsupportedException
+	 * @throws \KTXF\Resource\Exceptions\UnauthorizedException
+	 */
+	public function entityWriteChunk(string|int|null $collection, string|int $identifier, int $offset, string $data): int;
+
+}
--- a/shared/lib/Files/Service/IServiceMutable.php
+++ b/shared/lib/Files/Service/IServiceMutable.php
@@ -0,0 +1,30 @@
+<?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 KTXF\Json\JsonDeserializable;
+
+interface IServiceMutable extends IServiceBase, JsonDeserializable {
+
+	/**
+	 * Sets the localized human friendly name of this service
+	 *
+	 * @since 2025.11.01
+	 */
+	public function setLabel(string $value): static;
+
+	/**
+	 * Sets the active status of this service
+	 *
+	 * @since 2025.11.01
+	 */
+	public function setEnabled(bool $value): static;
+
+}