1037 lines
44 KiB
PHP
1037 lines
44 KiB
PHP
<?php
|
|
|
|
declare(strict_types=1);
|
|
|
|
namespace KTXM\MailManager;
|
|
|
|
use InvalidArgumentException;
|
|
use KTXC\Resource\ProviderManager;
|
|
use KTXF\Mail\Collection\CollectionBaseInterface;
|
|
use KTXF\Mail\Collection\CollectionMutableInterface;
|
|
use KTXF\Mail\Collection\ICollectionBase;
|
|
use KTXF\Mail\Entity\Address;
|
|
use KTXF\Mail\Entity\IMessageBase;
|
|
use KTXF\Mail\Entity\IMessageMutable;
|
|
use KTXF\Mail\Exception\SendException;
|
|
use KTXF\Mail\Provider\ProviderBaseInterface;
|
|
use KTXF\Mail\Provider\ProviderServiceDiscoverInterface;
|
|
use KTXF\Mail\Provider\ProviderServiceMutateInterface;
|
|
use KTXF\Mail\Provider\ProviderServiceTestInterface;
|
|
use KTXF\Mail\Queue\SendOptions;
|
|
use KTXF\Mail\Service\IServiceSend;
|
|
use KTXF\Mail\Service\ServiceBaseInterface;
|
|
use KTXF\Mail\Service\ServiceCollectionMutableInterface;
|
|
use KTXF\Resource\Filter\IFilter;
|
|
use KTXF\Resource\Provider\ResourceServiceIdentityInterface;
|
|
use KTXF\Resource\Provider\ResourceServiceLocationInterface;
|
|
use KTXF\Resource\Range\IRange;
|
|
use KTXF\Resource\Range\RangeAnchorType;
|
|
use KTXF\Resource\Range\RangeType;
|
|
use KTXF\Resource\Selector\CollectionSelector;
|
|
use KTXF\Resource\Selector\EntitySelector;
|
|
use KTXF\Resource\Selector\ServiceSelector;
|
|
use KTXF\Resource\Selector\SourceSelector;
|
|
use KTXF\Resource\Sort\ISort;
|
|
use KTXM\MailManager\Queue\MailQueueFile;
|
|
use Psr\Log\LoggerInterface;
|
|
|
|
/**
|
|
* Mail Manager
|
|
*
|
|
* Provides unified mail sending across multiple providers with context-aware
|
|
* service discovery and queued delivery support.
|
|
*/
|
|
class Manager {
|
|
|
|
public function __construct(
|
|
private LoggerInterface $logger,
|
|
private ProviderManager $providerManager,
|
|
private MailQueueFile $queue,
|
|
) { }
|
|
|
|
/**
|
|
* Retrieve available providers
|
|
*
|
|
* @param SourceSelector|null $sources collection of provider identifiers
|
|
*
|
|
* @return array<string,ProviderBaseInterface> collection of available providers e.g. ['provider1' => IProvider, 'provider2' => IProvider]
|
|
*/
|
|
public function providerList(string $tenantId, string $userId, ?SourceSelector $sources = null): array {
|
|
// determine filter from sources
|
|
$filter = ($sources !== null && $sources->identifiers() !== []) ? $sources->identifiers() : null;
|
|
// retrieve providers from provider manager
|
|
return $this->providerManager->providers(ProviderBaseInterface::TYPE_MAIL, $filter);
|
|
}
|
|
|
|
/**
|
|
* Confirm which providers are available
|
|
*
|
|
* @param SourceSelector|null $sources collection of provider identifiers to confirm
|
|
*
|
|
* @return array<string,bool> collection of providers and their availability status e.g. ['provider1' => true, 'provider2' => false]
|
|
*/
|
|
public function providerExtant(string $tenantId, string $userId, SourceSelector $sources): array {
|
|
// determine which providers are available
|
|
$providersResolved = $this->providerList($tenantId, $userId, $sources);
|
|
$providersAvailable = array_keys($providersResolved);
|
|
$providersUnavailable = array_diff($sources->identifiers(), $providersAvailable);
|
|
// construct response data
|
|
$responseData = array_merge(
|
|
array_fill_keys($providersAvailable, true),
|
|
array_fill_keys($providersUnavailable, false)
|
|
);
|
|
return $responseData;
|
|
}
|
|
|
|
/**
|
|
* Retrieve specific provider for specific user
|
|
*
|
|
* @param string $tenantId tenant identifier
|
|
* @param string $userId user identifier
|
|
* @param string $provider provider identifier
|
|
*
|
|
* @return ProviderBaseInterface
|
|
* @throws InvalidArgumentException
|
|
*/
|
|
public function providerFetch(string $tenantId, string $userId, string $provider): ProviderBaseInterface {
|
|
// retrieve provider
|
|
$providers = $this->providerList($tenantId, $userId, new SourceSelector([$provider => true]));
|
|
if (!isset($providers[$provider])) {
|
|
throw new InvalidArgumentException("Provider '$provider' not found");
|
|
}
|
|
return $providers[$provider];
|
|
}
|
|
|
|
/**
|
|
* Retrieve available services for specific user
|
|
*
|
|
* @param string $tenantId tenant identifier
|
|
* @param string $userId user identifier
|
|
* @param SourceSelector|null $sources list of provider and service identifiers
|
|
*
|
|
* @return array<string,<string,ServiceBaseInterface>> collections of available services e.g. ['provider1' => ['service1' => IServiceBase], 'provider2' => ['service2' => IServiceBase]]
|
|
*/
|
|
public function serviceList(string $tenantId, string $userId, ?SourceSelector $sources = null): array {
|
|
// retrieve providers
|
|
$providers = $this->providerList($tenantId, $userId, $sources);
|
|
// retrieve services for each provider
|
|
$responseData = [];
|
|
foreach ($providers as $provider) {
|
|
$serviceFilter = $sources[$provider->identifier()] instanceof ServiceSelector ? $sources[$provider->identifier()]->identifiers() : [];
|
|
$services = $provider->serviceList($tenantId, $userId, $serviceFilter);
|
|
$responseData[$provider->identifier()] = $services;
|
|
}
|
|
return $responseData;
|
|
}
|
|
|
|
/**
|
|
* Confirm which services are available
|
|
*
|
|
* @param string $tenantId tenant identifier
|
|
* @param string $userId user identifier
|
|
* @param SourceSelector|null $sources collection of provider and service identifiers to confirm
|
|
*
|
|
* @return array<string,bool> collection of providers and their availability status e.g. ['provider1' => ['service1' => false], 'provider2' => ['service2' => true, 'service3' => true]]
|
|
*/
|
|
public function serviceExtant(string $tenantId, string $userId, SourceSelector $sources): array {
|
|
// retrieve providers
|
|
$providers = $this->providerList($tenantId, $userId, $sources);
|
|
$providersRequested = $sources->identifiers();
|
|
$providersUnavailable = array_diff($providersRequested, array_keys($providers));
|
|
|
|
// initialize response with unavailable providers
|
|
$responseData = array_fill_keys($providersUnavailable, false);
|
|
|
|
// retrieve services for each available provider
|
|
foreach ($providers as $provider) {
|
|
$serviceSelector = $sources[$provider->identifier()];
|
|
$serviceAvailability = $provider->serviceExtant($tenantId, $userId, ...$serviceSelector->identifiers());
|
|
$responseData[$provider->identifier()] = $serviceAvailability;
|
|
}
|
|
return $responseData;
|
|
}
|
|
|
|
/**
|
|
* Retrieve service for specific user
|
|
*
|
|
* @param string $tenantId tenant identifier
|
|
* @param string $userId user identifier
|
|
* @param string $providerId provider identifier
|
|
* @param string|int $serviceId service identifier
|
|
*
|
|
* @return ServiceBaseInterface
|
|
* @throws InvalidArgumentException
|
|
*/
|
|
public function serviceFetch(string $tenantId, string $userId, string $providerId, string|int $serviceId): ServiceBaseInterface {
|
|
// retrieve provider and service
|
|
$service = $this->providerFetch($tenantId, $userId, $providerId)->serviceFetch($tenantId, $userId, $serviceId);
|
|
if ($service === null) {
|
|
throw new InvalidArgumentException("Service '$serviceId' not found for provider '$providerId'");
|
|
}
|
|
// retrieve services
|
|
return $service;
|
|
}
|
|
|
|
/**
|
|
* Find a service that handles a specific email address
|
|
*
|
|
* Searches all providers for a service that handles the given address,
|
|
* respecting the user context for scope filtering.
|
|
*
|
|
* @since 2025.05.01
|
|
*
|
|
* @param string $tenantId Tenant identifier
|
|
* @param string $userId User identifier
|
|
* @param string $address Email address to find service for
|
|
*
|
|
* @return ?ServiceBaseInterface
|
|
*/
|
|
public function serviceFindByAddress(string $tenantId, string $userId, string $address): ?ServiceBaseInterface {
|
|
// retrieve providers
|
|
$providers = $this->providerList($tenantId, $userId);
|
|
|
|
foreach ($providers as $providerId => $provider) {
|
|
$service = $provider->serviceFindByAddress($tenantId, $userId, $address);
|
|
if ($service !== null) {
|
|
return $service;
|
|
}
|
|
}
|
|
|
|
return null;
|
|
}
|
|
|
|
/**
|
|
* Create a new service
|
|
*
|
|
* @since 2025.05.01
|
|
*
|
|
* @param string $tenantId Tenant identifier
|
|
* @param string|null $userId User identifier for context
|
|
* @param string $providerId Provider identifier
|
|
* @param array $data Service configuration data
|
|
*
|
|
* @return ServiceBaseInterface Created service
|
|
*
|
|
* @throws InvalidArgumentException If provider doesn't support service creation
|
|
*/
|
|
public function serviceCreate(string $tenantId, ?string $userId, string $providerId, array $data): ServiceBaseInterface {
|
|
// retrieve provider and service
|
|
$provider = $this->providerFetch($tenantId, $userId, $providerId);
|
|
if ($provider instanceof ProviderServiceMutateInterface === false) {
|
|
throw new InvalidArgumentException("Provider '$providerId' does not support service creation");
|
|
}
|
|
|
|
// Create a fresh service instance
|
|
$service = $provider->serviceFresh();
|
|
|
|
// Deserialize the data into the service
|
|
$service->jsonDeserialize($data);
|
|
|
|
// Create the service
|
|
$serviceId = $provider->serviceCreate($tenantId, $userId, $service);
|
|
|
|
// Fetch and return the created service
|
|
return $provider->serviceFetch($tenantId, $userId, $serviceId);
|
|
}
|
|
|
|
/**
|
|
* Update an existing service
|
|
*
|
|
* @since 2025.05.01
|
|
*
|
|
* @param string $tenantId Tenant identifier
|
|
* @param string $userId User identifier for context
|
|
* @param string $providerId Provider identifier
|
|
* @param string|int $serviceId Service identifier
|
|
* @param array $data Updated service configuration data
|
|
*
|
|
* @return ServiceBaseInterface Updated service
|
|
*
|
|
* @throws InvalidArgumentException If provider doesn't support service modification or service not found
|
|
*/
|
|
public function serviceUpdate(string $tenantId, string $userId, string $providerId, string|int $serviceId, array $data): ServiceBaseInterface {
|
|
// retrieve provider and service
|
|
$provider = $this->providerFetch($tenantId, $userId, $providerId);
|
|
if ($provider instanceof ProviderServiceMutateInterface === false) {
|
|
throw new InvalidArgumentException("Provider '$providerId' does not support service creation");
|
|
}
|
|
|
|
// Fetch existing service
|
|
$service = $provider->serviceFetch($tenantId, $userId, $serviceId);
|
|
if ($service === null) {
|
|
throw new InvalidArgumentException("Service '$serviceId' not found");
|
|
}
|
|
|
|
// Update with new data
|
|
$service->jsonDeserialize($data);
|
|
|
|
// Modify the service
|
|
$provider->serviceModify($tenantId, $userId, $service);
|
|
|
|
// Fetch and return the updated service
|
|
return $provider->serviceFetch($tenantId, $userId, $serviceId);
|
|
}
|
|
|
|
/**
|
|
* Delete a service
|
|
*
|
|
* @since 2025.05.01
|
|
*
|
|
* @param string $tenantId Tenant identifier
|
|
* @param string $userId User identifier for context
|
|
* @param string $providerId Provider identifier
|
|
* @param string|int $serviceId Service identifier
|
|
*
|
|
* @return bool True if service was deleted
|
|
*
|
|
* @throws InvalidArgumentException If provider doesn't support service deletion or service not found
|
|
*/
|
|
public function serviceDelete(string $tenantId, string $userId, string $providerId, string|int $serviceId): bool {
|
|
// retrieve provider and service
|
|
$provider = $this->providerFetch($tenantId, $userId, $providerId);
|
|
if ($provider instanceof ProviderServiceMutateInterface === false) {
|
|
throw new InvalidArgumentException("Provider '$providerId' does not support service creation");
|
|
}
|
|
|
|
// Fetch existing service
|
|
$service = $provider->serviceFetch($tenantId, $userId, $serviceId);
|
|
if ($service === null) {
|
|
throw new InvalidArgumentException("Service '$serviceId' not found");
|
|
}
|
|
|
|
// Delete the service
|
|
return $provider->serviceDestroy($tenantId, $userId, $service);
|
|
}
|
|
|
|
/**
|
|
* Discover mail service settings from identity
|
|
*
|
|
* @since 2025.05.01
|
|
*
|
|
* @param string $tenantId Tenant identifier
|
|
* @param string $userId User identifier
|
|
* @param string|null $providerId Specific provider to use for discovery (or null for all)
|
|
* @param string $identity Identity to discover configuration for (e.g., email address)
|
|
* @param string|null $location Optional hostname to test directly (bypasses DNS SRV lookup)
|
|
* @param string|null $secret Optional password/token to validate discovered service
|
|
*
|
|
* @return array<string,ResourceServiceLocationInterface> Array of discovered service locations keyed by provider ID
|
|
* [
|
|
* 'jmap' => ResourceServiceLocationInterface,
|
|
* 'smtp' => ResourceServiceLocationInterface,
|
|
* // Only providers that successfully discovered (non-null)
|
|
* ]
|
|
*/
|
|
public function serviceDiscover(
|
|
string $tenantId,
|
|
string $userId,
|
|
string|null $providerId,
|
|
string $identity,
|
|
string|null $location = null,
|
|
string|null $secret = null
|
|
): array {
|
|
$locations = [];
|
|
|
|
$providers = $this->providerList($tenantId, $userId, $providerId !== null ? new SourceSelector([$providerId => true]) : null);
|
|
|
|
foreach ($providers as $providerId => $provider) {
|
|
if (!($provider instanceof ProviderServiceDiscoverInterface)) {
|
|
continue;
|
|
}
|
|
|
|
try {
|
|
$location = $provider->serviceDiscover($tenantId, $userId, $identity, $location, $secret);
|
|
|
|
if ($location !== null) {
|
|
$locations[$providerId] = $location;
|
|
}
|
|
} catch (\Throwable $e) {
|
|
$this->logger->warning('Provider autodiscovery failed', [
|
|
'provider' => $providerId,
|
|
'identity' => $identity,
|
|
'error' => $e->getMessage(),
|
|
]);
|
|
}
|
|
}
|
|
|
|
return $locations;
|
|
}
|
|
|
|
/**
|
|
* Test a mail service connection
|
|
*
|
|
* Tests connectivity and authentication for either an existing service
|
|
* or a fresh configuration. Delegates to the appropriate provider.
|
|
*
|
|
* @since 2025.05.01
|
|
*
|
|
* @param string $tenantId Tenant identifier
|
|
* @param string $userId User identifier for context
|
|
* @param string $providerId Provider ID (for existing service or targeted test)
|
|
* @param string|int|null $serviceId Service ID (for existing service test)
|
|
* @param ResourceServiceLocationInterface|array|null $location Service location (for fresh config test)
|
|
* @param ResourceServiceIdentityInterface|array|null $identity Service credentials (for fresh config test)
|
|
*
|
|
* @return array Test results
|
|
*
|
|
* @throws InvalidArgumentException If invalid parameters
|
|
*/
|
|
public function serviceTest(
|
|
string $tenantId,
|
|
string $userId,
|
|
string $providerId,
|
|
string|int|null $serviceId = null,
|
|
ResourceServiceLocationInterface|array|null $location = null,
|
|
ResourceServiceIdentityInterface|array|null $identity = null
|
|
): array {
|
|
// retrieve provider
|
|
$provider = $this->providerFetch($tenantId, $userId, $providerId);
|
|
if ($provider instanceof ProviderServiceTestInterface === false) {
|
|
throw new InvalidArgumentException("Provider '$providerId' does not support service testing");
|
|
}
|
|
|
|
// Testing existing service
|
|
if ($providerId !== null && $serviceId !== null) {
|
|
// retrieve service
|
|
$service = $this->serviceFetch($tenantId, $userId, $providerId, $serviceId);
|
|
if ($service === null) {
|
|
throw new InvalidArgumentException("Service not found: $providerId/$serviceId");
|
|
}
|
|
|
|
try {
|
|
return $provider->serviceTest($service);
|
|
} catch (\Throwable $e) {
|
|
throw new InvalidArgumentException('Service test failed: ' . $e->getMessage());
|
|
}
|
|
}
|
|
|
|
// Testing fresh configuration
|
|
if ($location !== null && $identity !== null) {
|
|
|
|
if ($provider instanceof ProviderServiceMutateInterface === false) {
|
|
throw new InvalidArgumentException("Provider '$providerId' does not support fresh service configuration testing");
|
|
}
|
|
|
|
if (empty($location['type'])) {
|
|
throw new InvalidArgumentException('Service location not valid');
|
|
}
|
|
|
|
if (empty($identity['type'])) {
|
|
throw new InvalidArgumentException('Service identity not valid');
|
|
}
|
|
|
|
/** @var ServiceMutableInterface $service */
|
|
$service = $provider->serviceFresh();
|
|
if ($location instanceof ResourceServiceLocationInterface === false) {
|
|
$location = $service->freshLocation($location['type'], (array)$location);
|
|
$service->setLocation($location);
|
|
}
|
|
if ($identity instanceof ResourceServiceIdentityInterface === false) {
|
|
$identity = $service->freshIdentity($identity['type'], (array)$identity);
|
|
$service->setIdentity($identity);
|
|
}
|
|
|
|
return $provider->serviceTest($service);
|
|
}
|
|
|
|
throw new InvalidArgumentException(
|
|
'Either (provider + service) or (provider + location + identity) must be provided'
|
|
);
|
|
}
|
|
|
|
// ==================== Collection Operations ====================
|
|
|
|
/**
|
|
* List collections across services
|
|
*
|
|
* @since 2025.05.01
|
|
*
|
|
* @param string $tenantId Tenant identifier
|
|
* @param string|null $userId User identifier for context
|
|
* @param SourceSelector|null $sources Provider/service sources
|
|
* @param IFilter|null $filter Collection filter
|
|
* @param ISort|null $sort Collection sort
|
|
*
|
|
* @return array<string, array<string|int, array<string|int, ICollectionBase>>> Collections grouped by provider/service
|
|
*/
|
|
public function collectionList(string $tenantId, ?string $userId, ?SourceSelector $sources = null, ?IFilter $filter = null, ?ISort $sort = null): array {
|
|
// confirm that sources are provided
|
|
if ($sources === null) {
|
|
$sources = new SourceSelector([]);
|
|
}
|
|
// retrieve providers
|
|
$providers = $this->providerList($tenantId, $userId, $sources);
|
|
// retrieve services for each provider
|
|
$responseData = [];
|
|
foreach ($providers as $provider) {
|
|
$serviceFilter = $sources[$provider->identifier()] instanceof ServiceSelector ? $sources[$provider->identifier()]->identifiers() : [];
|
|
/** @var ServiceBaseInterface[] $services */
|
|
$services = $provider->serviceList($tenantId, $userId, $serviceFilter);
|
|
// retrieve collections for each service
|
|
foreach ($services as $service) {
|
|
// construct filter for collections
|
|
$collectionFilter = null;
|
|
if ($filter !== null && $filter !== []) {
|
|
$collectionFilter = $service->collectionListFilter();
|
|
foreach ($filter as $attribute => $value) {
|
|
$collectionFilter->condition($attribute, $value);
|
|
}
|
|
}
|
|
// construct sort for collections
|
|
$collectionSort = null;
|
|
if ($sort !== null && $sort !== []) {
|
|
$collectionSort = $service->collectionListSort();
|
|
foreach ($sort as $attribute => $direction) {
|
|
$collectionSort->condition($attribute, $direction);
|
|
}
|
|
}
|
|
$collections = $service->collectionList('', $collectionFilter, $collectionSort);
|
|
if ($collections !== []) {
|
|
$responseData[$provider->identifier()][$service->identifier()] = $collections;
|
|
}
|
|
}
|
|
}
|
|
return $responseData;
|
|
}
|
|
|
|
/**
|
|
* Check if collections exist
|
|
*
|
|
* @since 2025.05.01
|
|
*
|
|
* @param string $tenantId Tenant identifier
|
|
* @param string|null $userId User identifier for context
|
|
* @param SourceSelector $sources Collection sources with identifiers
|
|
*
|
|
* @return array<string, array<string|int, array<string|int, bool>>> Existence map grouped by provider/service
|
|
*/
|
|
public function collectionExtant(string $tenantId, ?string $userId, SourceSelector $sources): array {
|
|
// retrieve available providers
|
|
$providers = $this->providerList($tenantId, $userId, $sources);
|
|
$providersRequested = $sources->identifiers();
|
|
$providersUnavailable = array_diff($providersRequested, array_keys($providers));
|
|
|
|
// initialize response with unavailable providers
|
|
$responseData = array_fill_keys($providersUnavailable, false);
|
|
|
|
// check services and collections for each available provider
|
|
foreach ($providers as $provider) {
|
|
$serviceSelector = $sources[$provider->identifier()];
|
|
$servicesRequested = $serviceSelector->identifiers();
|
|
/** @var ServiceBaseInterface[] $servicesAvailable */
|
|
$servicesAvailable = $provider->serviceList($tenantId, $userId, $servicesRequested);
|
|
$servicesUnavailable = array_diff($servicesRequested, array_keys($servicesAvailable));
|
|
|
|
// mark unavailable services as false
|
|
if ($servicesUnavailable !== []) {
|
|
$responseData[$provider->identifier()] = array_fill_keys($servicesUnavailable, false);
|
|
}
|
|
|
|
// confirm collections for each available service
|
|
foreach ($servicesAvailable as $service) {
|
|
$collectionSelector = $serviceSelector[$service->identifier()];
|
|
$collectionsRequested = $collectionSelector->identifiers();
|
|
|
|
if ($collectionsRequested === []) {
|
|
continue;
|
|
}
|
|
|
|
// check each requested collection
|
|
$collectionsAvailable = $service->collectionExtant(...$collectionsRequested);
|
|
$collectionsUnavailable = array_diff($collectionsRequested, array_keys($collectionsAvailable));
|
|
$responseData[$provider->identifier()][$service->identifier()] = array_merge(
|
|
$collectionsAvailable,
|
|
array_fill_keys($collectionsUnavailable, false)
|
|
);
|
|
}
|
|
}
|
|
return $responseData;
|
|
}
|
|
|
|
/**
|
|
* Fetch a specific collection
|
|
*
|
|
* @since 2025.05.01
|
|
*
|
|
* @param string $tenantId Tenant identifier
|
|
* @param string|null $userId User identifier for context
|
|
* @param string $providerId Provider identifier
|
|
* @param string|int $serviceId Service identifier
|
|
* @param string|int $collectionId Collection identifier
|
|
*
|
|
* @return CollectionBaseInterface|null
|
|
*/
|
|
public function collectionFetch(string $tenantId, ?string $userId, string $providerId, string|int $serviceId, string|int $collectionId): ?CollectionBaseInterface {
|
|
// retrieve service
|
|
$service = $this->serviceFetch($tenantId, $userId, $providerId, $serviceId);
|
|
if ($service === null) {
|
|
return null;
|
|
}
|
|
// retrieve collection
|
|
return $service->collectionFetch($collectionId);
|
|
}
|
|
|
|
/**
|
|
* Create a new collection for a specific user
|
|
*
|
|
* @param string $tenantId tenant identifier
|
|
* @param string $userId user identifier
|
|
* @param string $providerId provider identifier
|
|
* @param string|int $serviceId service identifier
|
|
* @param string|int|null $collectionId collection identifier (parent collection)
|
|
* @param CollectionMutableInterface|array $object collection to create
|
|
* @param array $options additional options for creation
|
|
*
|
|
* @return CollectionBaseInterface
|
|
* @throws InvalidArgumentException
|
|
*/
|
|
public function collectionCreate(string $tenantId, string $userId, string $providerId, string|int $serviceId, string|int|null $collectionId, CollectionMutableInterface|array $object, array $options = []): CollectionBaseInterface {
|
|
// retrieve service
|
|
$service = $this->serviceFetch($tenantId, $userId, $providerId, $serviceId);
|
|
|
|
// Check if service supports collection creation
|
|
if (!($service instanceof ServiceCollectionMutableInterface)) {
|
|
throw new InvalidArgumentException("Service does not support collection mutations");
|
|
}
|
|
if (!$service->capable(ServiceCollectionMutableInterface::CAPABILITY_COLLECTION_CREATE)) {
|
|
throw new InvalidArgumentException("Service is not capable of creating collections");
|
|
}
|
|
|
|
if (is_array($object)) {
|
|
$collection = $service->collectionFresh();
|
|
$collection->getProperties()->jsonDeserialize($object);
|
|
} else {
|
|
$collection = $object;
|
|
}
|
|
|
|
// Create collection
|
|
return $service->collectionCreate($collectionId, $collection, $options);
|
|
}
|
|
|
|
/**
|
|
* Modify an existing collection for a specific user
|
|
*
|
|
* @param string $tenantId tenant identifier
|
|
* @param string $userId user identifier
|
|
* @param string $providerId provider identifier
|
|
* @param string|int $serviceId service identifier
|
|
* @param string|int $collectionId collection identifier
|
|
* @param CollectionMutableInterface|array $object collection to modify
|
|
*
|
|
* @return CollectionBaseInterface
|
|
* @throws InvalidArgumentException
|
|
*/
|
|
public function collectionModify(string $tenantId, string $userId, string $providerId, string|int $serviceId, string|int $collectionId, CollectionMutableInterface|array $object): CollectionBaseInterface {
|
|
// retrieve service
|
|
$service = $this->serviceFetch($tenantId, $userId, $providerId, $serviceId);
|
|
|
|
// Check if service supports collection creation
|
|
if (!($service instanceof ServiceCollectionMutableInterface)) {
|
|
throw new InvalidArgumentException("Service does not support collection mutations");
|
|
}
|
|
if (!$service->capable(ServiceCollectionMutableInterface::CAPABILITY_COLLECTION_MODIFY)) {
|
|
throw new InvalidArgumentException("Service is not capable of modifying collections");
|
|
}
|
|
|
|
if (is_array($object)) {
|
|
$collection = $service->collectionFresh();
|
|
$collection->getProperties()->jsonDeserialize($object);
|
|
} else {
|
|
$collection = $object;
|
|
}
|
|
|
|
// Modify collection
|
|
return $service->collectionModify($collectionId, $collection);
|
|
}
|
|
|
|
/**
|
|
* Destroy a specific collection
|
|
*
|
|
* @since 2025.05.01
|
|
*
|
|
* @param string $tenantId Tenant identifier
|
|
* @param string|null $userId User identifier for context
|
|
* @param string $providerId Provider identifier
|
|
* @param string|int $serviceId Service identifier
|
|
* @param string|int $collectionId Collection identifier
|
|
*
|
|
* @return CollectionBaseInterface|null
|
|
*/
|
|
public function collectionDestroy(string $tenantId, ?string $userId, string $providerId, string|int $serviceId, string|int $collectionId, array $options = []): bool {
|
|
// retrieve service
|
|
$service = $this->serviceFetch($tenantId, $userId, $providerId, $serviceId);
|
|
|
|
// Check if service supports collection destruction
|
|
if (!($service instanceof ServiceCollectionMutableInterface)) {
|
|
throw new InvalidArgumentException("Service does not support collection mutations");
|
|
}
|
|
if (!$service->capable(ServiceCollectionMutableInterface::CAPABILITY_COLLECTION_DESTROY)) {
|
|
throw new InvalidArgumentException("Service is not capable of destroying collections");
|
|
}
|
|
|
|
$force = $options['force'] ?? false;
|
|
$recursive = $options['recursive'] ?? false;
|
|
|
|
// destroy collection
|
|
return $service->collectionDestroy($collectionId, $force, $recursive);
|
|
}
|
|
|
|
// ==================== Message Operations ====================
|
|
|
|
/**
|
|
* List messages in a collection
|
|
*
|
|
* @since 2025.05.01
|
|
*
|
|
* @param string $tenantId Tenant identifier
|
|
* @param string $userId User identifier
|
|
* @param SourceSelector $sources Message sources with collection identifiers
|
|
* @param array|null $filter Message filter
|
|
* @param array|null $sort Message sort
|
|
* @param array|null $range Message range/pagination
|
|
*
|
|
* @return array<string, array<string|int, array<string|int, array<string|int, IMessageBase>>>> Messages grouped by provider/service/collection
|
|
*/
|
|
public function entityList(string $tenantId, string $userId, SourceSelector $sources, array|null $filter = null, array|null $sort = null, array|null $range = null): array {
|
|
// retrieve providers
|
|
$providers = $this->providerList($tenantId, $userId, $sources);
|
|
// retrieve services for each provider
|
|
$responseData = [];
|
|
foreach ($providers as $provider) {
|
|
// retrieve services for each provider
|
|
$serviceSelector = $sources[$provider->identifier()];
|
|
$servicesSelected = $provider->serviceList($tenantId,$userId, $serviceSelector->identifiers());
|
|
/** @var ServiceBaseInterface $service */
|
|
foreach ($servicesSelected as $service) {
|
|
// retrieve collections for each service
|
|
$collectionSelector = $serviceSelector[$service->identifier()];
|
|
$collectionSelected = $collectionSelector instanceof CollectionSelector ? $collectionSelector->identifiers() : [];
|
|
if ($collectionSelected === []) {
|
|
$collections = $service->collectionList('');
|
|
$collectionSelected = array_map(
|
|
fn($collection) => $collection->identifier(),
|
|
$collections
|
|
);
|
|
}
|
|
if ($collectionSelected === []) {
|
|
continue;
|
|
}
|
|
// construct filter for entities
|
|
$entityFilter = null;
|
|
if ($filter !== null && $filter !== []) {
|
|
$entityFilter = $service->entityListFilter();
|
|
foreach ($filter as $attribute => $value) {
|
|
$entityFilter->condition($attribute, $value);
|
|
}
|
|
}
|
|
// construct sort for entities
|
|
$entitySort = null;
|
|
if ($sort !== null && $sort !== []) {
|
|
$entitySort = $service->entityListSort();
|
|
foreach ($sort as $attribute => $direction) {
|
|
$entitySort->condition($attribute, $direction);
|
|
}
|
|
}
|
|
// construct range for entities
|
|
$entityRange = null;
|
|
if ($range !== null && $range !== [] && isset($range['type'])) {
|
|
$entityRange = $service->entityListRange(RangeType::from($range['type']));
|
|
// Cast to IRangeTally if the range type is TALLY
|
|
if ($entityRange->type() === RangeType::TALLY) {
|
|
/** @var IRangeTally $entityRange */
|
|
if (isset($range['anchor'])) {
|
|
$entityRange->setAnchor(RangeAnchorType::from($range['anchor']));
|
|
}
|
|
if (isset($range['position'])) {
|
|
$entityRange->setPosition($range['position']);
|
|
}
|
|
if (isset($range['tally'])) {
|
|
$entityRange->setTally($range['tally']);
|
|
}
|
|
}
|
|
}
|
|
// retrieve entities for each collection
|
|
foreach ($collectionSelected as $collectionId) {
|
|
$entities = $service->entityList($collectionId, $entityFilter, $entitySort, $entityRange, null);
|
|
// skip collections with no entities
|
|
if ($entities === []) {
|
|
continue;
|
|
}
|
|
$responseData[$provider->identifier()][$service->identifier()][$collectionId] = $entities;
|
|
}
|
|
}
|
|
}
|
|
|
|
return $responseData;
|
|
}
|
|
|
|
/**
|
|
* Get message delta/changes
|
|
*
|
|
* @since 2025.05.01
|
|
*
|
|
* @param string $tenantId Tenant identifier
|
|
* @param string|null $userId User identifier for context
|
|
* @param SourceSelector $sources Message sources with signatures
|
|
*
|
|
* @return array<string, array<string|int, array<string|int, array>>> Delta grouped by provider/service/collection
|
|
*/
|
|
public function entityDelta(string $tenantId, string $userId, SourceSelector $sources): array {
|
|
// confirm that sources are provided
|
|
if ($sources === null) {
|
|
$sources = new SourceSelector([]);
|
|
}
|
|
// retrieve providers
|
|
$providers = $this->providerList($tenantId, $userId, $sources);
|
|
$providersRequested = $sources->identifiers();
|
|
$providersUnavailable = array_diff($providersRequested, array_keys($providers));
|
|
// initialize response with unavailable providers
|
|
$responseData = array_fill_keys($providersUnavailable, false);
|
|
// iterate through available providers
|
|
foreach ($providers as $provider) {
|
|
$serviceSelector = $sources[$provider->identifier()];
|
|
$servicesRequested = $serviceSelector instanceof ServiceSelector ? $serviceSelector->identifiers() : [];
|
|
/** @var ServiceBaseInterface[] $services */
|
|
$services = $provider->serviceList($tenantId, $userId, $servicesRequested);
|
|
$servicesUnavailable = array_diff($servicesRequested, array_keys($services));
|
|
if ($servicesUnavailable !== []) {
|
|
$responseData[$provider->identifier()] = array_fill_keys($servicesUnavailable, false);
|
|
}
|
|
// iterate through available services
|
|
foreach ($services as $service) {
|
|
$collectionSelector = $serviceSelector[$service->identifier()];
|
|
$collectionsRequested = $collectionSelector instanceof CollectionSelector ? $collectionSelector->identifiers() : [];
|
|
if ($collectionsRequested === []) {
|
|
$responseData[$provider->identifier()][$service->identifier()] = false;
|
|
continue;
|
|
}
|
|
foreach ($collectionsRequested as $collection) {
|
|
$entitySelector = $collectionSelector[$collection] ?? null;
|
|
$responseData[$provider->identifier()][$service->identifier()][$collection] = $service->entityDelta($collection, $entitySelector);
|
|
}
|
|
}
|
|
}
|
|
return $responseData;
|
|
}
|
|
|
|
/**
|
|
* Check if messages exist
|
|
*
|
|
* @since 2025.05.01
|
|
*
|
|
* @param string $tenantId Tenant identifier
|
|
* @param string|null $userId User identifier for context
|
|
* @param SourceSelector $sources Message sources with identifiers
|
|
*
|
|
* @return array<string, array<string|int, array<string|int, array<string|int, bool>>>> Existence map grouped by provider/service/collection
|
|
*/
|
|
public function entityExtant(string $tenantId, string $userId, SourceSelector $sources): array {
|
|
// confirm that sources are provided
|
|
if ($sources === null) {
|
|
$sources = new SourceSelector([]);
|
|
}
|
|
// retrieve available providers
|
|
$providers = $this->providerList($tenantId, $userId, $sources);
|
|
$providersRequested = $sources->identifiers();
|
|
$providersUnavailable = array_diff($providersRequested, array_keys($providers));
|
|
|
|
// initialize response with unavailable providers
|
|
$responseData = array_fill_keys($providersUnavailable, false);
|
|
|
|
// check services, collections, and entities for each available provider
|
|
foreach ($providers as $provider) {
|
|
$serviceSelector = $sources[$provider->identifier()];
|
|
$servicesRequested = $serviceSelector->identifiers();
|
|
/** @var ServiceBaseInterface[] $servicesAvailable */
|
|
$servicesAvailable = $provider->serviceList($tenantId, $userId, $servicesRequested);
|
|
$servicesUnavailable = array_diff($servicesRequested, array_keys($servicesAvailable));
|
|
|
|
// mark unavailable services as false
|
|
if ($servicesUnavailable !== []) {
|
|
$responseData[$provider->identifier()] = array_fill_keys($servicesUnavailable, false);
|
|
}
|
|
|
|
// check collections and entities for each available service
|
|
foreach ($servicesAvailable as $service) {
|
|
$collectionSelector = $serviceSelector[$service->identifier()];
|
|
$collectionsRequested = $collectionSelector instanceof CollectionSelector ? $collectionSelector->identifiers() : [];
|
|
|
|
if ($collectionsRequested === []) {
|
|
continue;
|
|
}
|
|
|
|
// check entities for each requested collection
|
|
foreach ($collectionsRequested as $collectionId) {
|
|
// first check if collection exists
|
|
$collectionExists = $service->collectionExtant((string)$collectionId);
|
|
|
|
if (!$collectionExists) {
|
|
// collection doesn't exist, mark as false
|
|
$responseData[$provider->identifier()][$service->identifier()][$collectionId] = false;
|
|
continue;
|
|
}
|
|
|
|
// extract entity identifiers from collection selector
|
|
$entitySelector = $collectionSelector[$collectionId];
|
|
|
|
// handle both array of entity IDs and boolean true (meaning check if collection exists)
|
|
if ($entitySelector instanceof EntitySelector) {
|
|
// check specific entities within the collection
|
|
$responseData[$provider->identifier()][$service->identifier()][$collectionId] = $service->entityExtant($collectionId, ...$entitySelector->identifiers());
|
|
} elseif ($entitySelector === true) {
|
|
// just checking if collection exists (already confirmed above)
|
|
$responseData[$provider->identifier()][$service->identifier()][$collectionId] = true;
|
|
}
|
|
}
|
|
}
|
|
}
|
|
return $responseData;
|
|
}
|
|
|
|
/**
|
|
* Fetch specific messages
|
|
*
|
|
* @since 2025.05.01
|
|
*
|
|
* @param string $tenantId Tenant identifier
|
|
* @param string|null $userId User identifier for context
|
|
* @param string $providerId Provider identifier
|
|
* @param string|int $serviceId Service identifier
|
|
* @param string|int $collectionId Collection identifier
|
|
* @param array<string|int> $identifiers Message identifiers
|
|
*
|
|
* @return array<string|int, IMessageBase> Messages indexed by ID
|
|
*/
|
|
public function entityFetch(string $tenantId, ?string $userId, string $providerId, string|int $serviceId, string|int $collectionId, array $identifiers): array {
|
|
$service = $this->serviceFetch($tenantId, $userId, $providerId, $serviceId);
|
|
|
|
// retrieve collection
|
|
return $service->entityFetch($collectionId, ...$identifiers);
|
|
}
|
|
|
|
/**
|
|
* Send a mail message
|
|
*
|
|
* Routes the message to the appropriate service based on the `from` address.
|
|
* By default, messages are queued; use SendOptions::immediate() for urgent messages.
|
|
*
|
|
* @since 2025.05.01
|
|
*
|
|
* @param string $tenantId Tenant identifier
|
|
* @param string|null $userId User identifier for context
|
|
* @param IMessageMutable $message Message to send
|
|
* @param SendOptions|null $options Delivery options (defaults to queued)
|
|
*
|
|
* @return string Job ID for queued messages, or Message ID for immediate sends
|
|
*
|
|
* @throws SendException On immediate send failure
|
|
* @throws InvalidArgumentException If no suitable service found
|
|
*/
|
|
public function entityTransmit(string $tenantId, ?string $userId, string $providerId, string|int $serviceId, array $data): string {
|
|
$options = $options ?? new SendOptions();
|
|
|
|
// Find the appropriate service
|
|
$from = $message->getFrom();
|
|
if ($from !== null) {
|
|
$service = $this->serviceFindByAddress($tenantId, $userId, $from->getAddress());
|
|
}
|
|
if ($service === null) {
|
|
throw new InvalidArgumentException('No mail service found for the message sender address');
|
|
}
|
|
|
|
// Verify service can send
|
|
if (!($service instanceof IServiceSend) || !$service->capable(IServiceSend::CAPABILITY_SEND)) {
|
|
throw new InvalidArgumentException('Selected mail service does not support sending');
|
|
}
|
|
|
|
// replace internal address for external 'from'
|
|
$message->setFrom((new Address())->setAddress('system@ktrix.local'));
|
|
|
|
// Immediate send bypasses queue
|
|
if ($options->immediate) {
|
|
$this->logger->debug('Sending mail immediately', [
|
|
'tenant' => $tenantId,
|
|
'provider' => $service->in(),
|
|
'service' => $service->id(),
|
|
'to' => array_map(fn($a) => $a->getAddress(), $message->getTo()),
|
|
]);
|
|
|
|
return $service->messageSend($message);
|
|
}
|
|
|
|
// Queue the message
|
|
$jobId = $this->queue->enqueue(
|
|
$tenantId,
|
|
$service->in(),
|
|
$service->id(),
|
|
$message,
|
|
$options
|
|
);
|
|
|
|
$this->logger->debug('Mail queued for delivery', [
|
|
'tenant' => $tenantId,
|
|
'jobId' => $jobId,
|
|
'provider' => $service->in(),
|
|
'service' => $service->id(),
|
|
'priority' => $options->priority,
|
|
]);
|
|
|
|
return $jobId;
|
|
}
|
|
|
|
|
|
/**
|
|
* Process queued mail for a tenant
|
|
*
|
|
* Called by the mail daemon to process pending messages.
|
|
*
|
|
* @since 2025.05.01
|
|
*
|
|
* @param string $tenantId Tenant identifier
|
|
* @param int $batchSize Maximum messages to process
|
|
*
|
|
* @return array{processed: int, failed: int}
|
|
*/
|
|
public function queueProcess(string $tenantId, int $batchSize = 50): array {
|
|
$processed = 0;
|
|
$failed = 0;
|
|
|
|
$jobs = $this->queue->dequeue($tenantId, $batchSize);
|
|
|
|
foreach ($jobs as $job) {
|
|
try {
|
|
$service = $this->serviceFetch($tenantId, null, $job->providerId, $job->serviceId);
|
|
|
|
if ($service === null || !($service instanceof IServiceSend)) {
|
|
throw new SendException("Service not found or cannot send: {$job->providerId}/{$job->serviceId}");
|
|
}
|
|
|
|
$messageId = $service->messageSend($job->message);
|
|
$this->queue->acknowledge($job->id, $messageId);
|
|
$processed++;
|
|
|
|
$this->logger->debug('Mail sent from queue', [
|
|
'tenant' => $tenantId,
|
|
'jobId' => $job->id,
|
|
'messageId' => $messageId,
|
|
]);
|
|
|
|
} catch (\Throwable $e) {
|
|
$isPermanent = $e instanceof SendException && $e->permanent;
|
|
$this->queue->reject($job->id, $e->getMessage(), !$isPermanent);
|
|
$failed++;
|
|
|
|
$this->logger->warning('Mail send failed', [
|
|
'tenant' => $tenantId,
|
|
'jobId' => $job->id,
|
|
'error' => $e->getMessage(),
|
|
'permanent' => $isPermanent,
|
|
]);
|
|
}
|
|
}
|
|
|
|
return ['processed' => $processed, 'failed' => $failed];
|
|
}
|
|
|
|
}
|