Blueprint: Public Mail Stack - C# Implementation

public sealed class LxcCommand
{
    internal LxcCommand(string subcommand, IReadOnlyList<string> argv)

    public string Subcommand { get; }
    public IReadOnlyList<string> Argv { get; }

    public string ToArgString()
    public ICommandResult ExecuteLocal(TimeSpan? timeout = null)
}

public sealed class Builder
{
    public static Builder Create()

    // Subcommand selection (one must be called):
    public Builder WithCreate(int ctid, string templatePath)
    public Builder WithStart(int ctid)
    public Builder WithStop(int ctid)
    public Builder WithDestroy(int ctid)
    public Builder WithExec(int ctid, string shellCmd)
    public Builder WithSet(int ctid)
    public Builder WithStatus(int ctid)

    // Option methods (AddNamed enforced - never raw Add for param+value):
    public Builder WithHostname(string hostname)
    public Builder WithMemory(int mb)
    public Builder WithCores(int n)
    public Builder WithRootfs(string storage, int diskGb)
    public Builder WithNet(int id, string bridge, string ip)
    public Builder WithFeatures(string features)
    public Builder WithUnprivileged(bool yes)
    public Builder WithOsType(string type)
    public Builder WithSshKey(AbsolutePath keyFile)
    public Builder WithPassword(string pw)

    public LxcCommand Build()
}

public sealed class ProvisionPmgLxcResult
{
    public bool SkippedExisting { get; init; }
    public int ContainerId { get; init; }
}

public static class ProvisionPmgLxc
{
    public const string DebianTemplateName = "debian-12-standard_12.7-1_amd64.tar.zst";
    public static readonly AbsolutePath LxcTemplateCacheDir =
        (AbsolutePath)"/var/lib/vz/template/cache";

    public static ProvisionPmgLxcResult Run(
        Host proxmoxHost, Machine machine, NETSetupConfig config, ISystemHost sysHost)

    public static ProvisionPmgLxcResult RunCore(
        Machine machine,
        string customerDomain,
        Func<bool> lxcExists,
        Action<int, string> ensureTemplate,
        Action<int, string> createLxc,
        Action<int> startLxc,
        Func<int, string, string> execInLxc,
        ILogger logger)
}

public enum LxcProvisionKind { Skip, Pmg }

public sealed class LxcProvisionOutcome
{
    public string LxcName { get; init; } = string.Empty;
    public LxcProvisionKind Kind { get; init; }
    public bool Success { get; init; }
    public string? Error { get; init; }
}

public sealed class EnsureCustomerLxcsResult
{
    public IReadOnlyList<LxcProvisionOutcome> Outcomes { get; init; } = Array.Empty<LxcProvisionOutcome>();
}

public static class EnsureCustomerLxcs
{
    public static LxcProvisionKind Classify(Machine machine)
    public static IReadOnlyList<Machine> GetOrderedLxcsForHost(NETSetupConfig config, SerialNumber hostSerial)
    public static void Run(ISystemHost host, NETSetupConfig config, IServiceProvider services)
    public static EnsureCustomerLxcsResult RunCore(
        IReadOnlyList<Machine> orderedLxcs,
        Action<Machine> provisionPmg,
        ILogger logger)
}

// osisa copyright header
using Nuke.Common.IO;

namespace NETSetup.Entities.Mail;

public sealed record MailRelayOptions
{
    public string Host { get; init; } = string.Empty;
    public int Port { get; init; } = 587;
    public string User { get; init; } = string.Empty;
    public AbsolutePath PassFile { get; init; } = (AbsolutePath)"/run/secrets/relay-pass";
}

// osisa copyright header
using System.Collections.Generic;
using Nuke.Common.IO;

namespace NETSetup.Entities.Dns;

public sealed record DnsProviderOptions
{
    // Provider name. MUST match a string supported by both lego (security.acme dnsProvider)
    // AND services.ddns-updater. Examples: "cloudflare", "duckdns", "porkbun", "namecheap",
    // "gandi", "hetzner", "godaddy", "ovh", "dyn", "noip".
    public string Provider { get; init; } = string.Empty;

    // Env-format file (KEY=value lines) decrypted by SOPS at runtime. Provider-specific
    // env-var contract per lego docs. Examples:
    //   cloudflare: CF_DNS_API_TOKEN=...
    //   duckdns:    DUCKDNS_TOKEN=...
    //   namecheap:  NAMECHEAP_API_USER=... NAMECHEAP_API_KEY=...
    public AbsolutePath CredentialsFile { get; init; } =
        (AbsolutePath)"/run/secrets/dns-provider-credentials";

    // Provider-specific extras not covered by env file (account IDs, zone IDs, etc.).
    // Passed verbatim into the ddns-updater settings attrset.
    public IReadOnlyDictionary<string, string>? CredentialsAttrs { get; init; }
}

public sealed class NixMailTemplate : NixHostTemplate
{
    public string CustomerDomain { get; set; } = string.Empty;
    public MailRelayOptions? Relay { get; set; }
    public string PmgLanIp { get; set; } = string.Empty;

    public override string GenerateDefaultNix() { ... }
}

var relayBlock = this.Relay is null
    ? "null"
    : $$"""
        {
            host = "{{this.Relay.Host}}";
            port = {{this.Relay.Port}};
            user = "{{this.Relay.User}}";
            passFile = "{{this.Relay.PassFile}}";
          }
        """;

public sealed class NixDnsTemplate : NixHostTemplate
{
    public string CustomerDomain { get; set; } = string.Empty;
    public DnsProviderOptions? DnsProvider { get; set; }
    public string MailLanIp { get; set; } = string.Empty;
    public string PmgLanIp { get; set; } = string.Empty;
    public bool AcmeStaging { get; set; } = true;
    public string AcmeContactEmail { get; set; } = string.Empty;

    public override string GenerateDefaultNix() { ... }
}

public static readonly OperatingSystem NixMail = OperatingSystem.From("NixMail", OperatingSystemFamily.Linux_GNU);
public static readonly OperatingSystem NixDns = OperatingSystem.From("NixDns", OperatingSystemFamily.Linux_GNU);
public static readonly OperatingSystem PmgLxc = OperatingSystem.From("PmgLxc", OperatingSystemFamily.Linux_GNU);

else if (os == NetsetupOS.NixMail)
{
    template = new NixMailTemplate();
}
else if (os == NetsetupOS.NixDns)
{
    template = new NixDnsTemplate();
}

public static NixHostTemplate ForMachine(Machine machine, NETSetupConfig config)
{
    if (machine is null) throw new ArgumentNullException(nameof(machine));
    if (config is null) throw new ArgumentNullException(nameof(config));

    var template = ForMachine(machine);
    var customerDomain = config.CustomerDomain
        ?? config.DirectoryService?.Name?.Value
        ?? string.Empty;

    if (template is NixMailTemplate mailTemplate)
    {
        mailTemplate.CustomerDomain = customerDomain;
        mailTemplate.Relay = config.MailRelay;
    }
    else if (template is NixDnsTemplate dnsTemplate)
    {
        dnsTemplate.CustomerDomain = customerDomain;
        dnsTemplate.DnsProvider = config.DnsProvider;
        dnsTemplate.AcmeContactEmail = $"admin@{customerDomain}";
    }

    return template;
}

public string? CustomerDomain { get; set; }
public MailRelayOptions? MailRelay { get; set; }
public DnsProviderOptions? DnsProvider { get; set; }

.AddDevice("mail@lib", DeviceTypes.Server)
.WithSerialNumber("102@lib")
.WithDescription("Mail")

.AddDevice("dns@lib", DeviceTypes.Server)
.WithSerialNumber("103@lib")
.WithDescription("Dns")

.AddDevice("pmg@lib", DeviceTypes.Server)
.WithSerialNumber("200@lib")
.WithDescription("PMG")

EnsurePbsInstalled(host);

host.Logger.LogInformation("Ensuring customer LXCs (PMG)...");
try
{
    EnsureCustomerLxcs.Run(host, config, services);
}
catch (Exception ex)
{
    host.Logger.LogError(ex, "EnsureCustomerLxcs failed during RunProxmoxUpdate.");
    throw;
}