<?php

declare(strict_types=1);

/**
 * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
 * SPDX-License-Identifier: AGPL-3.0-or-later
 */

namespace KTXF\Mail\Service;

use JsonSerializable;

/**
 * Mail Service Location Interface
 * 
 * Unified interface supporting both URI-based (API services) and socket-based
 * (traditional IMAP/SMTP) connection configurations.
 * 
 * @since 2025.05.01
 */
interface IServiceLocation extends JsonSerializable {

    public const TYPE_URI = 'uri';
    public const TYPE_SOCKET_SINGLE = 'socket-single';
    public const TYPE_SOCKET_SPLIT = 'socket-split';

    public const SECURITY_NONE = 'none';
    public const SECURITY_SSL = 'ssl';
    public const SECURITY_TLS = 'tls';
    public const SECURITY_STARTTLS = 'starttls';

    /**
     * Gets the location type
     * 
     * @since 2025.05.01
     * 
     * @return string One of: 'uri', 'socket-single', 'socket-split'
     */
    public function getType(): string;

    /**
     * Gets the URI for API-based services (JMAP, EWS, Graph API, HTTP relay)
     * 
     * @since 2025.05.01
     * 
     * @return string|null URI or null if not URI-based
     */
    public function getUri(): ?string;

    /**
     * Gets the inbound/primary host for socket-based services
     * 
     * @since 2025.05.01
     * 
     * @return string|null Hostname or null if URI-based
     */
    public function getInboundHost(): ?string;

    /**
     * Gets the inbound/primary port for socket-based services
     * 
     * @since 2025.05.01
     * 
     * @return int|null Port number or null if URI-based
     */
    public function getInboundPort(): ?int;

    /**
     * Gets the inbound/primary security mode
     * 
     * @since 2025.05.01
     * 
     * @return string|null One of: 'none', 'ssl', 'tls', 'starttls'
     */
    public function getInboundSecurity(): ?string;

    /**
     * Gets the outbound host for split-socket services (e.g., SMTP separate from IMAP)
     * 
     * @since 2025.05.01
     * 
     * @return string|null Hostname or null if not split-socket
     */
    public function getOutboundHost(): ?string;

    /**
     * Gets the outbound port for split-socket services
     * 
     * @since 2025.05.01
     * 
     * @return int|null Port number or null if not split-socket
     */
    public function getOutboundPort(): ?int;

    /**
     * Gets the outbound security mode for split-socket services
     * 
     * @since 2025.05.01
     * 
     * @return string|null One of: 'none', 'ssl', 'tls', 'starttls'
     */
    public function getOutboundSecurity(): ?string;

}