<?php

declare(strict_types=1);

namespace App\Administration\Application\Port;

use App\Administration\Domain\Model\Session\Location;

/**
 * Port interface for IP geolocation operations.
 *
 * This abstracts the geolocation mechanism, allowing the Application
 * layer to remain independent of the specific implementation
 * (e.g., MaxMind GeoLite2, IP-API, etc.).
 *
 * Current implementation: NullGeoLocationService (stores IP without resolution).
 * Future implementation: MaxMindGeoLocationService using GeoLite2-City database
 * for country/city resolution. This will be implemented when the feature is
 * prioritized (requires GeoLite2 license and periodic database updates).
 *
 * @see Story 1.6 - Gestion des sessions
 */
interface GeoLocationService
{
    /**
     * Locate an IP address.
     *
     * Returns Location with country and city if available,
     * or Location::unknown() if geolocation fails.
     */
    public function locate(string $ipAddress): Location;
}
