| 1 | open module Service |
| 2 | |
| 3 | import "site.pkl" as site |
| 4 | |
| 5 | const nomadHostPort = "{{ if regexMatch \":\" .Address }}[{{ .Address }}]{{ else }}{{ .Address }}{{ end }}:{{ .Port }}" |
| 6 | |
| 7 | /// One HTTP listener and its public route. |
| 8 | class Http { |
| 9 | containerPort: UInt16 |
| 10 | hostPort: UInt16? |
| 11 | loopback: Boolean = false |
| 12 | subdomain: String? |
| 13 | authRole: String? |
| 14 | /// Backend header set from the authenticated OIDC preferred username. |
| 15 | userHeader: String? |
| 16 | /// Identity headers copied from a valid SSO session; anonymous requests continue. |
| 17 | identityHeaders: Mapping<String, String> = new {} |
| 18 | /// Set X-Real-Ip from Caddy's observed client address before proxying. |
| 19 | forwardRealIp: Boolean = false |
| 20 | /// Require HTTPS when browsers send cookies issued by this route. |
| 21 | secureCookies: Boolean = false |
| 22 | /// Generated secret whose value becomes the private proxy header name. |
| 23 | identityProofSecret: String? |
| 24 | /// Additional hosts routed to this container without SSO headers. |
| 25 | plainHostnames: Listing<String> = new {} |
| 26 | hostname: String? = read?("prop:hostname") ?? if (subdomain != null) "\(subdomain).\(site.domain)" else null |
| 27 | tlsInternal: Boolean = site.tlsInternal |
| 28 | checkPath: String = "/" |
| 29 | /// Internal Prometheus endpoint collected by the home server dashboard. |
| 30 | metricsPath: String? |
| 31 | checkHeaders: Mapping<String, String> = new {} |
| 32 | /// API paths authenticated by a sibling task, bypassing the browser login proxy. |
| 33 | apiPaths: Mapping<String, String> = new {} |
| 34 | /// Request path to a file or directory in this service's folder. |
| 35 | overrideFiles: Mapping<String, String> = new {} |
| 36 | /// HTML inserted before </head> for the listed page paths. |
| 37 | headHtml: Mapping<String, String> = new {} |
| 38 | } |
| 39 | |
| 40 | /// One TCP listener published through Nomad. |
| 41 | class Tcp { |
| 42 | name: String |
| 43 | containerPort: UInt16 |
| 44 | hostPort: UInt16? |
| 45 | loopback: Boolean = true |
| 46 | } |
| 47 | |
| 48 | /// A container mount, keyed by its absolute path inside the container. |
| 49 | class Volume { |
| 50 | /// Host source; absent means the same path beneath this service's data root. |
| 51 | src: String? |
| 52 | /// File or directory relative to this service's assets folder; copied into a read-only mount. |
| 53 | config: String? |
| 54 | readOnly: Boolean = config != null |
| 55 | } |
| 56 | |
| 57 | /// A persistent value generated when the service is first provisioned. |
| 58 | class GeneratedSecret { |
| 59 | bytes: Int(isBetween(16, 128)) = 32 |
| 60 | } |
| 61 | |
| 62 | /// Provider-owned resource request; the alias names its allocated secret. |
| 63 | open class Requirement { |
| 64 | alias: String |
| 65 | fixed provider: String |
| 66 | fixed kind: String |
| 67 | } |
| 68 | |
| 69 | /// One Podman task. A service can contain one or several of these. |
| 70 | class Container { |
| 71 | /// Use either an image or a build directory in this service's release folder. |
| 72 | image: String? |
| 73 | build: String? |
| 74 | entrypoint: String? |
| 75 | http: Http? |
| 76 | tcp: Listing<Tcp> = new {} |
| 77 | volumes: Mapping<String, Volume> = new {} |
| 78 | /// Podman tmpfs mounts for data that must not persist in service storage. |
| 79 | tmpfs: Listing<String> = new {} |
| 80 | /// `${secret.own.key}` and `${secret.alias.key}` resolve from Nomad variables. |
| 81 | env: Mapping<String, String> = new {} |
| 82 | /// Nomad template for environment values resolved after allocation. |
| 83 | envTemplate: String? |
| 84 | /// Nomad templates rendered privately and mounted read-only at absolute container paths. |
| 85 | secretFiles: Mapping<String, String> = new {} |
| 86 | args: Listing<String> = new {} |
| 87 | capAdd: Listing<String> = new {} |
| 88 | readOnlyRoot: Boolean = false |
| 89 | killTimeout: String? |
| 90 | devices: Listing<String> = new {} |
| 91 | extraHosts: Listing<String> = new {} |
| 92 | hostNetwork: Boolean = false |
| 93 | imageUser: Boolean = false |
| 94 | /// Prestart tasks finish first; prestart sidecars stay up for the main tasks. |
| 95 | lifecycle: "main"|"prestart"|"prestartSidecar" = "main" |
| 96 | rootGroup: Boolean = false |
| 97 | cpu: Int = 200 |
| 98 | memory: Int = 512 |
| 99 | } |
| 100 | |
| 101 | /// Stable internal ID supplied from the service definition name by the caller. |
| 102 | id: String = read?("prop:serviceId") |
| 103 | /// Stable numeric owner assigned by the deployment tool. |
| 104 | uid: Int = read("prop:uid").toInt() |
| 105 | /// Name shown in the management UI and service listings. |
| 106 | name: String |
| 107 | tagline: String = "" |
| 108 | launcher: Boolean = true |
| 109 | /// Discovery group; absent uses the public route's auth role. |
| 110 | access: String? |
| 111 | /// Allows site-specific services to stay out of deployments where they would cause side effects. |
| 112 | enabled: Boolean = true |
| 113 | /// Simple replaces one allocation; overlapped runs a canary alongside it. |
| 114 | rollout: String = "simple" |
| 115 | /// Fresh previews create empty storage and new secrets instead of forking production. |
| 116 | stageIsolation: "clone"|"fresh" = "clone" |
| 117 | /// Include the managed dataset in deployment backup snapshots. |
| 118 | snapshots: Boolean = true |
| 119 | /// Time allowed for a new allocation to pass its service checks. |
| 120 | healthyDeadline: String? |
| 121 | /// Delay before persistent health-check failures may restart a running allocation. |
| 122 | healthRestartGrace: String? |
| 123 | /// Repeatable service configuration run after a healthy deployment. |
| 124 | setup: String? |
| 125 | /// Service-owned data preparation before its container starts. |
| 126 | prepare: String? |
| 127 | /// Handler for input requests owned by this service. |
| 128 | provide: String? |
| 129 | |
| 130 | /// Use this for one container; it becomes the "app" task in the output. |
| 131 | container: Container? |
| 132 | |
| 133 | /// Use this instead of `container` when the service has named tasks. |
| 134 | containers: Mapping<String, Container>? |
| 135 | |
| 136 | secrets: Mapping<String, GeneratedSecret> = new {} |
| 137 | /// Secret names supplied from outside the release, in import-file line order. |
| 138 | requiredSecrets: Listing<String> = new {} |
| 139 | requirements: Listing<Requirement> = new {} |
| 140 | /// Service startup dependency with no resource to allocate. |
| 141 | dependsOn: Listing<String> = new {} |
| 142 | /// Resource service.name emitted by this app's trace exporter. |
| 143 | traceServiceName: String? |
| 144 | /// Metrics sent by the app over OTLP instead of a Prometheus HTTP endpoint. |
| 145 | metricsPushed: Boolean = false |
| 146 | |
| 147 | local deploymentContainers: Mapping<String, Container> = |
| 148 | if (!enabled) |
| 149 | new Mapping {} |
| 150 | else if (container != null && containers != null) |
| 151 | throw("Declare either container or containers, not both") |
| 152 | else if (container != null) |
| 153 | new Mapping { ["app"] = container!! } |
| 154 | else if (containers != null && !containers!!.isEmpty) |
| 155 | containers!! |
| 156 | else if (!requirements.isEmpty) |
| 157 | new Mapping {} |
| 158 | else |
| 159 | throw("Declare a container or an input") |
| 160 | |
| 161 | local vmStartupGrace: String? = if (read?("env:SNOWGLOBE_VM_ACCEL") == "qemu") "60m" else null |
| 162 | |
| 163 | output { |
| 164 | renderer = new JsonRenderer {} |
| 165 | value = new { |
| 166 | id = module.id |
| 167 | name = module.name |
| 168 | tagline = module.tagline |
| 169 | launcher = module.launcher |
| 170 | access = module.access |
| 171 | rollout = module.rollout |
| 172 | stageIsolation = module.stageIsolation |
| 173 | snapshots = module.snapshots |
| 174 | healthyDeadline = vmStartupGrace ?? module.healthyDeadline |
| 175 | healthRestartGrace = vmStartupGrace ?? module.healthRestartGrace |
| 176 | hostRoot = "\(site.root)/prod/\(module.id)" |
| 177 | stagingRoot = "\(site.root)/staging" |
| 178 | pool = site.pool |
| 179 | cloverRoot = site.cloverRoot |
| 180 | cloverGid = site.cloverGid |
| 181 | mediaRoot = site.mediaRoot |
| 182 | ownerEmail = site.ownerEmail |
| 183 | containers = deploymentContainers |
| 184 | setup = module.setup |
| 185 | prepare = module.prepare |
| 186 | provide = module.provide |
| 187 | // External mounts do not require this service's dataset. |
| 188 | hasManagedVolumes = deploymentContainers.toMap().values.any((task) -> |
| 189 | task.volumes.toMap().values.any((volume) -> volume.src == null && volume.config == null)) |
| 190 | secrets = module.secrets |
| 191 | requiredSecrets = module.requiredSecrets |
| 192 | requirements = module.requirements |
| 193 | dependsOn = module.dependsOn |
| 194 | traceServiceName = module.traceServiceName |
| 195 | metricsPushed = module.metricsPushed |
| 196 | } |
| 197 | } |