resource provider and service improvements
This commit is contained in:
root
@@ -1,132 +0,0 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
/**
|
||||
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
|
||||
* SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
*/
|
||||
|
||||
namespace KTXF\Mail\Provider;
|
||||
|
||||
use JsonSerializable;
|
||||
use KTXF\Mail\Selector\ServiceSelector;
|
||||
use KTXF\Mail\Service\IServiceBase;
|
||||
|
||||
/**
|
||||
* Mail Provider Base Interface
|
||||
*
|
||||
* Core interface for mail providers with context-aware service discovery.
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*/
|
||||
interface IProviderBase extends JsonSerializable {
|
||||
|
||||
public const CAPABILITY_SERVICE_LIST = 'ServiceList';
|
||||
public const CAPABILITY_SERVICE_FETCH = 'ServiceFetch';
|
||||
public const CAPABILITY_SERVICE_EXTANT = 'ServiceExtant';
|
||||
public const CAPABILITY_SERVICE_FIND_BY_ADDRESS = 'ServiceFindByAddress';
|
||||
|
||||
public const JSON_TYPE = 'mail.provider';
|
||||
public const JSON_PROPERTY_TYPE = '@type';
|
||||
public const JSON_PROPERTY_ID = 'id';
|
||||
public const JSON_PROPERTY_LABEL = 'label';
|
||||
public const JSON_PROPERTY_CAPABILITIES = 'capabilities';
|
||||
|
||||
/**
|
||||
* Confirms if a specific capability is supported
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @param string $value Required capability e.g. 'ServiceList'
|
||||
*
|
||||
* @return bool
|
||||
*/
|
||||
public function capable(string $value): bool;
|
||||
|
||||
/**
|
||||
* Lists all supported capabilities
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @return array<string,bool>
|
||||
*/
|
||||
public function capabilities(): array;
|
||||
|
||||
/**
|
||||
* Gets the unique identifier for this provider
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @return string Provider ID (e.g., 'smtp', 'imap', 'jmap')
|
||||
*/
|
||||
public function id(): string;
|
||||
|
||||
/**
|
||||
* Gets the localized human-friendly name of this provider
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @return string Provider label (e.g., 'SMTP Mail Provider')
|
||||
*/
|
||||
public function label(): string;
|
||||
|
||||
/**
|
||||
* Lists services for a tenant, optionally filtered by user context
|
||||
*
|
||||
* When userId is null, returns only System-scoped services.
|
||||
* When userId is provided, returns System-scoped services plus
|
||||
* User-scoped services owned by that user.
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @param string $tenantId Tenant identifier
|
||||
* @param string|null $userId User identifier for context (null = system only)
|
||||
* @param ServiceSelector|null $selector Optional filter criteria
|
||||
*
|
||||
* @return array<string|int, IServiceBase>
|
||||
*/
|
||||
public function serviceList(string $tenantId, ?string $userId = null, ?ServiceSelector $selector = null): array;
|
||||
|
||||
/**
|
||||
* Checks if specific services exist
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @param string $tenantId Tenant identifier
|
||||
* @param string|null $userId User identifier for context
|
||||
* @param string|int ...$identifiers Service identifiers to check
|
||||
*
|
||||
* @return array<string|int, bool> Identifier => exists
|
||||
*/
|
||||
public function serviceExtant(string $tenantId, ?string $userId, string|int ...$identifiers): array;
|
||||
|
||||
/**
|
||||
* Fetches a specific service by identifier
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @param string $tenantId Tenant identifier
|
||||
* @param string|null $userId User identifier for context
|
||||
* @param string|int $identifier Service identifier
|
||||
*
|
||||
* @return IServiceBase|null
|
||||
*/
|
||||
public function serviceFetch(string $tenantId, ?string $userId, string|int $identifier): ?IServiceBase;
|
||||
|
||||
/**
|
||||
* Finds a service that handles a specific email address
|
||||
*
|
||||
* Searches within the appropriate scope based on userId context.
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @param string $tenantId Tenant identifier
|
||||
* @param string|null $userId User identifier for context
|
||||
* @param string $address Email address to find service for
|
||||
*
|
||||
* @return IServiceBase|null Service handling the address, or null
|
||||
*/
|
||||
public function serviceFindByAddress(string $tenantId, ?string $userId, string $address): ?IServiceBase;
|
||||
|
||||
}
|
||||
@@ -1,77 +0,0 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
/**
|
||||
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
|
||||
* SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
*/
|
||||
|
||||
namespace KTXF\Mail\Provider;
|
||||
|
||||
use KTXF\Json\JsonDeserializable;
|
||||
use KTXF\Mail\Service\IServiceBase;
|
||||
|
||||
/**
|
||||
* Mail Provider Service Mutate Interface
|
||||
*
|
||||
* Optional interface for providers that support service CRUD operations.
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*/
|
||||
interface IProviderServiceMutate extends JsonDeserializable {
|
||||
|
||||
public const CAPABILITY_SERVICE_FRESH = 'ServiceFresh';
|
||||
public const CAPABILITY_SERVICE_CREATE = 'ServiceCreate';
|
||||
public const CAPABILITY_SERVICE_MODIFY = 'ServiceModify';
|
||||
public const CAPABILITY_SERVICE_DESTROY = 'ServiceDestroy';
|
||||
|
||||
/**
|
||||
* Creates a new blank service instance for configuration
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @return IServiceBase Fresh service object
|
||||
*/
|
||||
public function serviceFresh(): IServiceBase;
|
||||
|
||||
/**
|
||||
* Creates a new service configuration
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @param string $tenantId Tenant identifier
|
||||
* @param string|null $userId Owner user ID (null for system services)
|
||||
* @param IServiceBase $service Service configuration to create
|
||||
*
|
||||
* @return string|int Created service identifier
|
||||
*/
|
||||
public function serviceCreate(string $tenantId, ?string $userId, IServiceBase $service): string|int;
|
||||
|
||||
/**
|
||||
* Modifies an existing service configuration
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @param string $tenantId Tenant identifier
|
||||
* @param string|null $userId User identifier for authorization context
|
||||
* @param IServiceBase $service Service configuration to update
|
||||
*
|
||||
* @return string|int Updated service identifier
|
||||
*/
|
||||
public function serviceModify(string $tenantId, ?string $userId, IServiceBase $service): string|int;
|
||||
|
||||
/**
|
||||
* Destroys a service configuration
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @param string $tenantId Tenant identifier
|
||||
* @param string|null $userId User identifier for authorization context
|
||||
* @param IServiceBase $service Service to destroy
|
||||
*
|
||||
* @return bool True if destroyed, false if not found
|
||||
*/
|
||||
public function serviceDestroy(string $tenantId, ?string $userId, IServiceBase $service): bool;
|
||||
|
||||
}
|
||||
41
shared/lib/Mail/Provider/ProviderBaseInterface.php
Normal file
41
shared/lib/Mail/Provider/ProviderBaseInterface.php
Normal file
@@ -0,0 +1,41 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
/**
|
||||
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
|
||||
* SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
*/
|
||||
|
||||
namespace KTXF\Mail\Provider;
|
||||
|
||||
use KTXF\Mail\Service\ServiceBaseInterface;
|
||||
use KTXF\Resource\Provider\ResourceProviderBaseInterface;
|
||||
|
||||
/**
|
||||
* Mail Provider Base Interface
|
||||
*
|
||||
* Core interface for mail providers with context-aware service discovery.
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*/
|
||||
interface ProviderBaseInterface extends ResourceProviderBaseInterface{
|
||||
|
||||
public const JSON_TYPE = 'mail.provider';
|
||||
|
||||
/**
|
||||
* Finds a service that handles a specific email address
|
||||
*
|
||||
* Searches within the appropriate scope based on userId context.
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @param string $tenantId Tenant identifier
|
||||
* @param string|null $userId User identifier for context
|
||||
* @param string $address Email address to find service for
|
||||
*
|
||||
* @return IServiceBase|null Service handling the address, or null
|
||||
*/
|
||||
public function serviceFindByAddress(string $tenantId, ?string $userId, string $address): ?ServiceBaseInterface;
|
||||
|
||||
}
|
||||
@@ -0,0 +1,67 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
/**
|
||||
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
|
||||
* SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
*/
|
||||
|
||||
namespace KTXF\Mail\Provider;
|
||||
|
||||
/**
|
||||
* Mail Provider Autodiscovery Interface
|
||||
*
|
||||
* Optional interface for mail providers that support automatic service discovery
|
||||
* from email addresses or domains. Providers implementing this interface can
|
||||
* discover mail service configurations using various methods specific to their
|
||||
* protocol or provider type.
|
||||
*
|
||||
* Examples:
|
||||
* - IMAP/SMTP providers: Mozilla Autoconfig, DNS SRV, well-known URIs
|
||||
* - JMAP providers: Well-known JMAP endpoint discovery
|
||||
* - Provider-specific: Gmail, Outlook, etc. with known configurations
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*/
|
||||
interface ProviderServiceDiscoverInterface extends ProviderBaseInterface {
|
||||
|
||||
public const CAPABILITY_SERVICE_DISCOVER = 'ServiceDiscover';
|
||||
|
||||
/**
|
||||
* Discover service configuration
|
||||
*
|
||||
* Attempts to discover service configuration using provider-specific methods.
|
||||
* Each provider may use different discovery mechanisms:
|
||||
* - IMAP/SMTP: config database, DNS SRV, well-known URIs, common patterns
|
||||
* - JMAP: Well-known JMAP session discovery
|
||||
* - Provider-specific: Known configurations for popular providers
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @param string $identity Identity to discover configuration for
|
||||
* @param array $options Provider-specific options (e.g., preferred protocols, timeout)
|
||||
*
|
||||
* @return array Discovery results in the format:
|
||||
* [
|
||||
* 'domain' => 'example.com',
|
||||
* 'provider' => 'gmail|outlook|generic|etc', // Optional detected provider
|
||||
* 'results' => [
|
||||
* [
|
||||
* 'protocol' => 'imap|smtp|jmap|etc',
|
||||
* 'host' => 'imap.example.com',
|
||||
* 'port' => 993,
|
||||
* 'security' => 'ssl|tls|starttls|none',
|
||||
* 'authentication' => ['plain', 'login', 'oauth2'], // Supported auth methods
|
||||
* 'confidence' => 'high|medium|low',
|
||||
* 'source' => 'mozilla|srv|wellknown|common|verified', // Discovery method used
|
||||
* ],
|
||||
* // ... more protocol results
|
||||
* ]
|
||||
* ]
|
||||
*
|
||||
* Returns empty results array if no configuration could be discovered.
|
||||
*/
|
||||
public function serviceDiscover(string $identity, array $options = []): array;
|
||||
|
||||
}
|
||||
33
shared/lib/Mail/Provider/ProviderServiceMutateInterface.php
Normal file
33
shared/lib/Mail/Provider/ProviderServiceMutateInterface.php
Normal file
@@ -0,0 +1,33 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
/**
|
||||
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
|
||||
* SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
*/
|
||||
|
||||
namespace KTXF\Mail\Provider;
|
||||
|
||||
use KTXF\Resource\Provider\ResourceProviderServiceMutateInterface;
|
||||
|
||||
/**
|
||||
* Mail Provider Service Mutate Interface
|
||||
*
|
||||
* Optional interface for providers that support service CRUD operations.
|
||||
*
|
||||
* Implementations return ServiceMutableInterface instances (which extend ResourceServiceMutateInterface).
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @method ServiceMutableInterface serviceFresh() Construct a new blank mail service instance
|
||||
* @method string serviceCreate(string $tenantId, ?string $userId, ServiceMutableInterface $service) Create a mail service configuration
|
||||
* @method string serviceModify(string $tenantId, ?string $userId, ServiceMutableInterface $service) Modify a mail service configuration
|
||||
* @method bool serviceDestroy(string $tenantId, ?string $userId, ServiceMutableInterface $service) Delete a mail service configuration
|
||||
*/
|
||||
interface ProviderServiceMutateInterface extends ProviderBaseInterface, ResourceProviderServiceMutateInterface {
|
||||
|
||||
// Methods inherited from ResourceProviderServiceMutateInterface
|
||||
// Implementations should return/accept ServiceMutableInterface instances
|
||||
|
||||
}
|
||||
79
shared/lib/Mail/Provider/ProviderServiceTestInterface.php
Normal file
79
shared/lib/Mail/Provider/ProviderServiceTestInterface.php
Normal file
@@ -0,0 +1,79 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
/**
|
||||
* SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
|
||||
* SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
*/
|
||||
|
||||
namespace KTXF\Mail\Provider;
|
||||
|
||||
use KTXF\Mail\Service\ServiceBaseInterface;
|
||||
|
||||
/**
|
||||
* Mail Provider Service Test Interface
|
||||
*
|
||||
* Optional interface for mail providers that support testing service connections.
|
||||
* Providers implementing this interface can validate connection parameters,
|
||||
* test authentication, and verify service availability before creating a
|
||||
* persistent service configuration.
|
||||
*
|
||||
* Supports two testing modes:
|
||||
* 1. Testing an existing service (validate current configuration)
|
||||
* 2. Testing a fresh configuration (validate before saving)
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*/
|
||||
interface ProviderServiceTestInterface extends ProviderBaseInterface {
|
||||
|
||||
public const CAPABILITY_SERVICE_TEST = 'ServiceTest';
|
||||
|
||||
/**
|
||||
* Test a service connection
|
||||
*
|
||||
* Tests connectivity, authentication, and capabilities of a service.
|
||||
*
|
||||
* For new services: use serviceFresh() to create a service, configure it with
|
||||
* setters, then pass it to this method for testing before persisting.
|
||||
*
|
||||
* For existing services: fetch the service and pass it directly.
|
||||
*
|
||||
* @since 2025.05.01
|
||||
*
|
||||
* @param ServiceBaseInterface $service Service to test (can be fresh/unsaved or existing)
|
||||
* @param array $options Provider-specific test options:
|
||||
* - 'timeout' => int (seconds, default: 10)
|
||||
* - 'verify_ssl' => bool (default: true)
|
||||
* - 'test_send' => bool (attempt test send if capable, default: false)
|
||||
* - 'test_receive' => bool (attempt mailbox access if capable, default: true)
|
||||
*
|
||||
* @return array Test results in the format:
|
||||
* [
|
||||
* 'success' => bool,
|
||||
* 'message' => 'Connection successful' | 'Error message',
|
||||
* 'details' => [
|
||||
* 'connected' => bool, // Socket/HTTP connection succeeded
|
||||
* 'authenticated' => bool, // Authentication succeeded
|
||||
* 'capabilities' => ['IMAP4rev1', ...], // Server capabilities (if applicable)
|
||||
* 'serverInfo' => 'Server version/banner',
|
||||
* 'latency' => 123, // Connection time in milliseconds
|
||||
* 'protocols' => [
|
||||
* 'inbound' => [
|
||||
* 'connected' => bool,
|
||||
* 'authenticated' => bool,
|
||||
* 'error' => 'error message if failed'
|
||||
* ],
|
||||
* 'outbound' => [ // For split-socket (IMAP+SMTP)
|
||||
* 'connected' => bool,
|
||||
* 'authenticated' => bool,
|
||||
* 'error' => 'error message if failed'
|
||||
* ]
|
||||
* ],
|
||||
* 'errors' => ['Error 1', 'Error 2'], // List of errors encountered
|
||||
* ]
|
||||
* ]
|
||||
*/
|
||||
public function serviceTest(ServiceBaseInterface $service, array $options = []): array;
|
||||
|
||||
}
|
||||
Reference in New Issue
Block a user