feat: GeoIP session enrichment and LCG assignment

Add an IP enrichment service backed by the MaxMind GeoLite2 ASN and City
databases, configured under OpenShock:Geo (AsnDbPath, CityDbPath). When
neither database is available the service returns null and callers fall
back to the previous behavior.

Login sessions:
- Record ASN organization, VPN flag, country code and city when a session
  is created, and expose them on LoginSessionResponse.
- IsVpn is nullable so a failed or missing ASN lookup stays unknown rather
  than being reported as "not VPN".
- VPN detection matches whole tokens against consumer VPN providers only,
  so datacenter/cloud egress is not flagged and substrings like "pia" in
  "Olympia" don't match.

Gateway assignment:
- LCGs can advertise an optional Latitude/Longitude, published on the
  LcgNode in Redis.
- Hub assignment still picks the closest region by country, then narrows
  it by great-circle distance to the hub's GeoIP location when every node
  in that region has coordinates.
- LcgKeepAlive now overwrites the whole node on every beat instead of
  diffing fields, which also backfills nodes written by older builds.

A default GeoOptions is registered in AddOpenShockServices so hosts that
don't configure Geo (Cron, LCG, SeedE2E) still resolve the service.

Co-authored-by: LucHeart <luc@luc.cat>

Author: hhvrc

API.IntegrationTests/GeoLocatedWebApplicationFactory.cs

@@ -0,0 +1,42 @@
+using System.Net;
+using Microsoft.AspNetCore.Hosting;
+using Microsoft.AspNetCore.TestHost;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.DependencyInjection.Extensions;
+using OpenShock.Common.Services.Geo;
+
+namespace OpenShock.API.IntegrationTests;
+
+/// <summary>
+/// Variant of <see cref="WebApplicationFactory"/> whose GeoIP lookup resolves every request to
+/// <see cref="ClientLocation"/>, so tests can place the caller without shipping a GeoLite2 database.
+/// </summary>
+public sealed class GeoLocatedWebApplicationFactory : WebApplicationFactory
+{
+    private readonly FakeIpEnrichmentService _enrichment = new();
+
+    public GeoPoint? ClientLocation
+    {
+        get => _enrichment.Location;
+        set => _enrichment.Location = value;
+    }
+
+    protected override void ConfigureWebHost(IWebHostBuilder builder)
+    {
+        base.ConfigureWebHost(builder);
+
+        builder.ConfigureTestServices(services =>
+        {
+            services.RemoveAll<IIpEnrichmentService>();
+            services.AddSingleton<IIpEnrichmentService>(_enrichment);
+        });
+    }
+
+    private sealed class FakeIpEnrichmentService : IIpEnrichmentService
+    {
+        public GeoPoint? Location { get; set; }
+
+        public IpEnrichmentData? Enrich(IPAddress ip) =>
+            Location is { } location ? new IpEnrichmentData(null, null, null, null, location, 20) : null;
+    }
+}

API.IntegrationTests/Tests/LcgCoordinateAssignmentTests.cs

@@ -0,0 +1,200 @@
+using System.Net;
+using System.Net.Http.Json;
+using Microsoft.AspNetCore.Hosting;
+using Microsoft.EntityFrameworkCore;
+using Microsoft.Extensions.DependencyInjection;
+using OpenShock.API.Models.Response;
+using OpenShock.Common.OpenShockDb;
+using OpenShock.Common.Redis;
+using OpenShock.Common.Services.Geo;
+using OpenShock.Common.Utils;
+using OpenShock.Internal.Common.Utils;
+using Redis.OM.Contracts;
+
+namespace OpenShock.API.IntegrationTests.Tests;
+
+public sealed class LcgCoordinateAssignmentTests
+{
+    [ClassDataSource<GeoLocatedWebApplicationFactory>(Shared = SharedType.PerTestSession)]
+    public required GeoLocatedWebApplicationFactory WebApplicationFactory { get; init; }
+
+    // Shares the key with LcgAssignmentTests: both suites wipe the same Redis node collection.
+    private const string ParalellGateway = "gateway_assignment";
+
+    private static readonly GeoPoint Seattle = new(47.61, -122.33);
+    private static readonly GeoPoint NewYork = new(40.71, -74.01);
+    private static readonly GeoPoint Oregon = new(45.60, -121.18);
+    private static readonly GeoPoint Virginia = new(39.04, -77.49);
+    private static readonly GeoPoint Frankfurt = new(50.11, 8.68);
+    private static readonly GeoPoint Munich = new(48.14, 11.58);
+    private static readonly GeoPoint Hamburg = new(53.55, 9.99);
+    private static readonly GeoPoint Vienna = new(48.21, 16.37);
+
+    private Guid _userId;
+    private Guid _hubId;
+    private string _hubToken = string.Empty;
+
+    [Before(Test)]
+    public async Task Setup()
+    {
+        await using var context = WebApplicationFactory.Services.CreateAsyncScope();
+        var db = context.ServiceProvider.GetRequiredService<OpenShockContext>();
+
+        _userId = Guid.CreateVersion7();
+        _hubId = Guid.CreateVersion7();
+        _hubToken = CryptoUtils.RandomString(256);
+
+        db.Users.Add(new User
+        {
+            Id = _userId,
+            Name = _userId.ToString("N"),
+            Email = $"{_userId}@test.org",
+            PasswordHash = HashingUtils.HashPassword("password")
+        });
+        db.Devices.Add(new Device
+        {
+            Id = _hubId,
+            Name = "TestHub",
+            OwnerId = _userId,
+            Token = _hubToken,
+            CreatedAt = DateTime.UtcNow
+        });
+        await db.SaveChangesAsync();
+    }
+
+    [After(Test)]
+    public async Task Teardown()
+    {
+        WebApplicationFactory.ClientLocation = null;
+
+        await using var context = WebApplicationFactory.Services.CreateAsyncScope();
+        var db = context.ServiceProvider.GetRequiredService<OpenShockContext>();
+        var lcgNodesCollection = context.ServiceProvider.GetRequiredService<IRedisConnectionProvider>().RedisCollection<LcgNode>(false);
+
+        await db.Devices.Where(x => x.Id == _hubId).ExecuteDeleteAsync();
+        await db.Users.Where(x => x.Id == _userId).ExecuteDeleteAsync();
+
+        var allLcg = await lcgNodesCollection.ToListAsync();
+        await lcgNodesCollection.DeleteAsync(allLcg);
+    }
+
+    [Test]
+    [NotInParallel(ParalellGateway)]
+    public async Task PicksClosestGatewayWithinSameCountry()
+    {
+        // Both gateways are "US", so the country table alone ties them; coordinates break the tie.
+        await AddGateway("us-west.example.com", "US", Oregon);
+        await AddGateway("us-east.example.com", "US", Virginia);
+
+        WebApplicationFactory.ClientLocation = Seattle;
+        await Assert.That(await AssignHost("US")).IsEqualTo("us-west.example.com");
+
+        WebApplicationFactory.ClientLocation = NewYork;
+        await Assert.That(await AssignHost("US")).IsEqualTo("us-east.example.com");
+    }
+
+    [Test]
+    [NotInParallel(ParalellGateway)]
+    public async Task UsesCoordinatesWithoutCountryHeader()
+    {
+        await AddGateway("us-west.example.com", "US", Oregon);
+        await AddGateway("de1.example.com", "DE", Frankfurt);
+
+        WebApplicationFactory.ClientLocation = Seattle;
+        await Assert.That(await AssignHost(null)).IsEqualTo("us-west.example.com");
+    }
+
+    [Test]
+    [NotInParallel(ParalellGateway)]
+    public async Task FallsBackToCountryWhenClientHasNoLocation()
+    {
+        await AddGateway("us-west.example.com", "US", Oregon);
+        await AddGateway("de1.example.com", "DE", Frankfurt);
+
+        WebApplicationFactory.ClientLocation = null;
+        await Assert.That(await AssignHost("DE")).IsEqualTo("de1.example.com");
+    }
+
+    [Test]
+    [NotInParallel(ParalellGateway)]
+    public async Task FallsBackToCountryForGatewayWithoutLocation()
+    {
+        // A gateway that has not configured coordinates must still be assignable by country.
+        await AddGateway("us-west.example.com", "US", Oregon);
+        await AddGateway("de1.example.com", "DE", null);
+
+        WebApplicationFactory.ClientLocation = Frankfurt;
+        await Assert.That(await AssignHost("DE")).IsEqualTo("de1.example.com");
+    }
+
+    [Test]
+    [NotInParallel(ParalellGateway)]
+    public async Task CoordinatesOverrideLoadWithinRegion()
+    {
+        // Baseline for MixedCoordinatesLeaveRegionUntouched: with full coordinates, distance wins over load.
+        await AddGateway("us-west.example.com", "US", Oregon, load: 5);
+        await AddGateway("us-east.example.com", "US", Virginia, load: 0);
+
+        WebApplicationFactory.ClientLocation = Seattle;
+        await Assert.That(await AssignHost("US")).IsEqualTo("us-west.example.com");
+    }
+
+    [Test]
+    [NotInParallel(ParalellGateway)]
+    public async Task MixedCoordinatesLeaveRegionUntouched()
+    {
+        // us-east has no coordinates, so the US region can't be ranked fairly and must fall back to
+        // pure load balancing, rather than us-east winning on a 0 km same-country score.
+        await AddGateway("us-west.example.com", "US", Oregon, load: 0);
+        await AddGateway("us-east.example.com", "US", null, load: 5);
+
+        WebApplicationFactory.ClientLocation = NewYork;
+        await Assert.That(await AssignHost("US")).IsEqualTo("us-west.example.com");
+    }
+
+    [Test]
+    [NotInParallel(ParalellGateway)]
+    public async Task CoordinatesDoNotCrossCountryPick()
+    {
+        // Munich is nearer Vienna than Hamburg, but coordinates only refine the country pick.
+        await AddGateway("de1.example.com", "DE", Hamburg);
+        await AddGateway("at1.example.com", "AT", Vienna);
+
+        WebApplicationFactory.ClientLocation = Munich;
+        await Assert.That(await AssignHost("DE")).IsEqualTo("de1.example.com");
+    }
+
+    private async Task AddGateway(string host, string country, GeoPoint? location, byte load = 0)
+    {
+        await using var context = WebApplicationFactory.Services.CreateAsyncScope();
+        var environment = context.ServiceProvider.GetRequiredService<IWebHostEnvironment>();
+        var lcgNodesCollection = context.ServiceProvider.GetRequiredService<IRedisConnectionProvider>().RedisCollection<LcgNode>(false);
+
+        await lcgNodesCollection.InsertAsync(new LcgNode
+        {
+            Id = host,
+            Host = host,
+            Port = 443,
+            Country = country,
+            Latitude = location?.Latitude,
+            Longitude = location?.Longitude,
+            Load = load,
+            Environment = environment.EnvironmentName
+        });
+    }
+
+    private async Task<string> AssignHost(string? requesterCountry)
+    {
+        var httpRequest = new HttpRequestMessage(HttpMethod.Get, "/2/device/assignLCG?version=2");
+        httpRequest.Headers.Add("Device-Token", _hubToken);
+        if (!string.IsNullOrEmpty(requesterCountry)) httpRequest.Headers.Add("CF-IPCountry", requesterCountry);
+
+        using var client = WebApplicationFactory.CreateClient();
+        using var response = await client.SendAsync(httpRequest);
+        await Assert.That(response.StatusCode).IsEqualTo(HttpStatusCode.OK);
+
+        var data = await response.Content.ReadFromJsonAsync<LcgNodeResponseV2>();
+        await Assert.That(data).IsNotNull();
+        return data!.Host;
+    }
+}

API/Controller/Device/AssignLCG.cs

@@ -5,6 +5,7 @@
 using OpenShock.API.Services.LCGNodeProvisioner;
 using OpenShock.Common.Errors;
 using OpenShock.Common.Problems;
+using OpenShock.Common.Services.Geo;
 using OpenShock.Common.Utils;
 using OpenShock.Common.Models;
 
@@ -23,15 +24,15 @@ public sealed partial class DeviceController
     [MapToApiVersion("1")]
     [ProducesResponseType<LegacyDataResponse<LcgNodeResponse>>(StatusCodes.Status200OK, MediaTypeNames.Application.Json)]
     [ProducesResponseType<OpenShockProblem>(StatusCodes.Status503ServiceUnavailable, MediaTypeNames.Application.ProblemJson)] // NoLcgNodesAvailable
-    public async Task<IActionResult> GetLiveControlGateway([FromServices] ILCGNodeProvisioner geoLocation)
+    public async Task<IActionResult> GetLiveControlGateway([FromServices] ILCGNodeProvisioner geoLocation, [FromServices] IIpEnrichmentService ipEnrichment)
     {
         if (!HttpContext.TryGetCFIPCountryCode(out var countryCode))
         {
             _logger.LogWarning("CF-IPCountry header could not be parsed into a alpha2 country code");
         }
 
         try {
-        var closestNode = await geoLocation.GetOptimalNodeAsync(countryCode);
+        var closestNode = await geoLocation.GetOptimalNodeAsync(countryCode, ipEnrichment.Enrich(HttpContext.GetRemoteIP())?.Location);
         if (closestNode is null) return Problem(AssignLcgError.NoLcgNodesAvailable);
 
         return LegacyDataOk(new LcgNodeResponse

API/Controller/Device/AssignLCGV2.cs

@@ -5,6 +5,7 @@
 using OpenShock.API.Services.LCGNodeProvisioner;
 using OpenShock.Common.Errors;
 using OpenShock.Common.Problems;
+using OpenShock.Common.Services.Geo;
 using OpenShock.Common.Utils;
 
 using OpenShock.Internal.Common.Problems;
@@ -23,7 +24,7 @@ public sealed partial class DeviceController
     [ProducesResponseType<LcgNodeResponseV2>(StatusCodes.Status200OK, MediaTypeNames.Application.Json)]
     [ProducesResponseType<OpenShockProblem>(StatusCodes.Status400BadRequest, MediaTypeNames.Application.ProblemJson)] // BadSchemaVersion
     [ProducesResponseType<OpenShockProblem>(StatusCodes.Status503ServiceUnavailable, MediaTypeNames.Application.ProblemJson)] // NoLcgNodesAvailable
-    public async Task<IActionResult> GetLiveControlGatewayV2([FromQuery(Name = "version")] uint version, [FromServices] ILCGNodeProvisioner geoLocation)
+    public async Task<IActionResult> GetLiveControlGatewayV2([FromQuery(Name = "version")] uint version, [FromServices] ILCGNodeProvisioner geoLocation, [FromServices] IIpEnrichmentService ipEnrichment)
     {
         string path;
         switch (version)
@@ -43,7 +44,7 @@ public async Task<IActionResult> GetLiveControlGatewayV2([FromQuery(Name = "vers
             _logger.LogWarning("CF-IPCountry header could not be parsed into a alpha2 country code");
         }
 
-        var closestNode = await geoLocation.GetOptimalNodeAsync(countryCode);
+        var closestNode = await geoLocation.GetOptimalNodeAsync(countryCode, ipEnrichment.Enrich(HttpContext.GetRemoteIP())?.Location);
         if (closestNode is null) return Problem(AssignLcgError.NoLcgNodesAvailable);
 
         return Ok(new LcgNodeResponseV2

API/Models/Response/LoginSessionResponse.cs

@@ -13,7 +13,11 @@ public static LoginSessionResponse MapFrom(LoginSession session)
             UserAgent = session.UserAgent,
             Created = session.Created!.Value,
             Expires = session.Expires!.Value,
-            LastUsed = session.LastUsed
+            LastUsed = session.LastUsed,
+            AsnOrg = session.AsnOrg,
+            IsVpn = session.IsVpn,
+            CountryCode = session.CountryCode,
+            City = session.City,
         };
     }
 
@@ -23,4 +27,8 @@ public static LoginSessionResponse MapFrom(LoginSession session)
     public required DateTimeOffset Created { get; init; }
     public required DateTimeOffset Expires { get; init; }
     public required DateTimeOffset? LastUsed { get; init; }
-}
+    public string? AsnOrg { get; init; }
+    public bool? IsVpn { get; init; }
+    public string? CountryCode { get; init; }
+    public string? City { get; init; }
+}

API/Program.cs

@@ -26,6 +26,7 @@
 var databaseOptions = builder.RegisterDatabaseOptions();
 builder.RegisterMetricsOptions();
 builder.RegisterFrontendOptions();
+builder.RegisterGeoOptions();
 builder.RegisterAccountOptions();
 // The API never sends mail, but it must know whether anything ever will: with mail disabled there is
 // no activation link, so accounts are activated on creation instead of waiting for one.

API/Services/LCGNodeProvisioner/ILCGNodeProvisioner.cs

@@ -1,10 +1,18 @@
 using OpenShock.Internal.Common.Geo;
 using OpenShock.Common.Redis;
+using OpenShock.Common.Services.Geo;
 
 namespace OpenShock.API.Services.LCGNodeProvisioner;
 
 public interface ILCGNodeProvisioner
 {
     public Task<LcgNode?> GetOptimalNodeAsync();
     public Task<LcgNode?> GetOptimalNodeAsync(Alpha2CountryCode countryCode);
+
+    /// <summary>
+    /// Picks the closest, least loaded node. The closest region is chosen by country; when
+    /// <paramref name="clientLocation"/> is known and every node in that region has coordinates, the
+    /// region is further narrowed to the nodes nearest the client.
+    /// </summary>
+    public Task<LcgNode?> GetOptimalNodeAsync(Alpha2CountryCode countryCode, GeoPoint? clientLocation);
 }