All files / suite/blong-suite server.ts

0% Statements 0/262
0% Branches 0/1
0% Functions 0/1
0% Lines 0/262

Press n or j to go to the next uncovered block, b, p or k for the previous block.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             
import {server} from '@feasibleone/blong';
import pkg from './package.json' with {type: 'json'};

export default server(() => ({
    url: import.meta.url,
    pkg: {
        name: pkg.name,
        version: pkg.version,
    },
    children: [
        /** Built-in blong-browser realm: RPC, auth, portal, auth orchestrators */
        async function srv() {
            return import('@feasibleone/blong-server/server.ts');
        },
        async function login() {
            return import('@feasibleone/blong-login/server.ts');
        },
        async function core() {
            return import('@feasibleone/blong-core/server.ts');
        },
        async function access() {
            return import('@feasibleone/blong-access/server.ts');
        },
        /** Marine biology demonstration realm */
        async function marine() {
            return import('@feasibleone/blong-marine/server.ts');
        },
        /**
         * The records this deployment's own processes wrote: the `viewer` realm's UDP receiver and
         * the gateway routes the page reads through (`@@D-946`). A deployable realm, so a split
         * profile gives it a process of its own and a Service named after it; in dev it rides this
         * process, which is what makes a developer's own run show its own records.
         */
        async function viewer() {
            return import('@feasibleone/blong-viewer/server.ts');
        },
        // The deployment realm is not listed here on purpose: it is one of the framework's own
        // realms, so the loader adds it under the intents it names for itself (`frameworkRealms` in
        // `core/blong-gogo/src/load.ts`) as soon as this suite declares
        // `@feasibleone/blong-kustomize` as a dependency. Those are `k8s` and nothing else, because a
        // suite declaring the package for its `k8s` run saying something about the processes it
        // *deploys* was the accident: a business pod carried the deployment realm's layers and ports
        // (T-254). A process that does want its read API says so with
        // `framework.realms: {kustomize: true}`. The browser side still names it, because Vite has
        // to see the specifier in the source to bundle it.
    ],
    config: {
        // The deployment settings live in `default` rather than in the `k8s` block that generates
        // the tree, because two intents have to agree on them: the generator writes the manifests
        // from them, and the operator — a serving process, which runs `release` — re-derives the
        // same plan when it reconciles a CR. A CR names what a tenant may change (the suite, the
        // volume, the services, the entry); the CRD and the operator itself are the installer's
        // decisions, and a setting that appears only under `k8s` makes an operator pass report
        // objects it does not manage as drift.
        default: {
            kustomize: {
                deploy: {
                    // No `layout` here, on purpose: the realm's `k8s` activation names the repository
                    // half (`base`, in `realm/blong-kustomize/orchestrator/deploy.ts`), so a bare run
                    // writes the tree a repository keeps and the deploy names `local` beside it
                    // (D-475, D-490).
                    // No `realmRoles` here: a realm declares what it *is* in its own `server.ts`
                    // config (`k8sRealmRole`), which is both closer to the truth — `core` and `access`
                    // know they are carried *and* published, `server` knows every microservice repeats
                    // it — and immune to the two spellings of one realm (`server` the framework name,
                    // `srv` the child's), because the answer travels with the realm rather than with
                    // the name it was loaded under (D-433, T-238).
                    suite: {
                        name: 'blong-suite',
                        namespace: 'blong-suite',
                        // Read from the package beside this file rather than repeated here: the
                        // version labels every generated object and names the artifact volume, so a
                        // literal is a second place to keep in step with `package.json`, and the
                        // release that bumps the package is the release that ships the tree (Q4).
                        version: pkg.version,
                        // The framework's version, which is a different thing: it is the image tag,
                        // so the tree says `blong-gogo:1`.
                        minFrameworkVersion: '1',
                        // No tag: the generator appends the version itself, so the reference it
                        // emits is `<frameworkImage>:<version>`.
                        frameworkImage: 'docker.io/library/blong-gogo',
                        // `rush deploy` mirrors the repository's category folders, so the entry sits
                        // two levels down rather than at the artifact root the default assumes (the
                        // GitHub release zip is the flattened variant). Absolute because the runner
                        // imports the entry as given: a relative one resolves against the runner's
                        // own module, not the working directory (F-360).
                        entry: '/opt/deploy/suite/suite/blong-suite/index.ts',
                    },
                    // profile: 'monolith',
                    // The cluster's own MySQL, reached through an ExternalName Service: the suite
                    // keeps naming `db` and the cluster decides what `db` is (Phase 5).
                    externalServices: {
                        db: {
                            externalName: 'mysql.blong-integration.svc.cluster.local',
                            ports: [{name: 'mysql', port: 3306}],
                        },
                    },
                    // No `services` key, and the silence is the answer rather than an omission: the
                    // plan offers what an activated adapter implies — a `knex` adapter implies a
                    // MySQL — and `services.<name>` is where a deployment says which of them it
                    // brings (D-504). This suite brings none, because it dials `db`, the cluster's
                    // MySQL through the `ExternalName` above: a generated one would be a second, empty
                    // instance in `blong-services` that nothing reaches.
                    //
                    // `false` and silence generate the same tree — an absent key is the absence of a
                    // decision, not a refusal — so writing `mysql: false` here would be a line that
                    // changes nothing but the committed sample. What it must not be is the *other*
                    // shape: `mysql: {databases: ['blong-integration'], credentials: {generate: true}}`
                    // asked the tree to bring one, and that mistake was repaired in a local rc until it
                    // was removed here, where the default belongs (F-752). A deployment that does want
                    // its own writes that shape — the databases the suite's connections name, which a
                    // `k8s` plan cannot read off the `release` block it does not merge (T-277), and the
                    // credentials a database whose own users are created from them needs (D-509).
                    //
                    // A portal names its address, the process that answers beside it and the alias
                    // that names its Service. The host is the e2e run's: the cluster's own ingress
                    // controller answers it, and the runbook reaches the suite by sending that Host
                    // rather than by port-forwarding, which is what makes the published path an
                    // assertion instead of a manifest nobody dials. `marine` is the realm whose
                    // process answers beside the page — the one `both` realm, so it has a process of
                    // its own *and* every other process carries it — while the bundle itself is
                    // served by the asset server the tree deploys. The alias is what names the
                    // portal and
                    // its Service (`web-http`), and it is a map rather than a list so a suite config,
                    // a CR and an overlay can each add a portal without knowing the others.
                    //
                    // The host above is the *fallback*, not the deployment's address: a `k8s` run
                    // reads `kustomize.deploy.portal.web.host` from the rc file beside this package
                    // and that is what the ingress carries (@@D-645). `tls.secretName` is the suite's
                    // own statement — that it publishes a page, and which Secret cert-manager writes
                    // the certificate into — the same way `realm/blong-sport` names `sport-tls`.
                    //
                    // `realm` names the process behind the portal's documentation Service
                    // (`web-http`): it is what catches `/documentation`. It no longer serves `/s/` —
                    // the bundle is served by the asset server, which `realm/blong-kustomize`
                    // deploys beside the suite's processes — and it no longer has to be a process
                    // that answers everything the menu reaches: the tree writes `/rpc/<namespace>`
                    // per deployment (@@D-736), so `core`, `access`, `login` and `marine` each reach
                    // the pod that serves them.
                    // `marine` stays because it is the realm the suite is about and the one the
                    // portal drives at steady state; what it decides now is only which process
                    // serves `/documentation`.
                    portal: {
                        web: {
                            host: 'blong-suite.test',
                            realm: 'marine',
                            tls: {secretName: 'marine-tls'},
                            annotations: {
                                'cert-manager.io/cluster-issuer': 'letsencrypt-prod',
                            },
                        },
                    },
                    suiteVolume: {
                        backend: 'nodeLocal',
                        artifact: {
                            source: 'url',
                            // A file server in the cluster: the fill Job runs `curl` inside
                            // a pod, so the artifact has to be reachable from the nodes by name. Its
                            // own namespace is not required — the suite namespace resolves the
                            // fully-qualified name.
                            url: 'http://blong-artifact.default.svc.cluster.local/suite.zip',
                        },
                    },
                    crd: true,
                },
            },
        },
        // What a process still serves for itself, now that the deployed tree gives `/s/` to the
        // asset server: the browser build is the suite package's own `vite build`, which emits
        // `dist/` beside the entry the line above names, and `/s` is the prefix that build's `base`
        // uses. The built-in plugin stays useful for a run that reaches a pod directly rather than
        // through the Ingress, and it is what a development run uses. Naming the root is safe before
        // the pipeline that fills it exists: the static plugin warns and serves nothing when the
        // directory is not there.
        release: {
            // How a *deployed* process finds another realm's process: the Service of that name. It
            // belongs here rather than beside the deployment settings, because only a released
            // process is split: the default profile this suite deploys with (`realm`) gives each
            // realm a Deployment of its own, so a method another realm owns has to cross a Service
            // boundary. Without it every such dispatch dials `127.0.0.1` — the portal answered
            // `Not Found` for `marine.coral.find` while the marine pod was running, and
            // `blong.flow.find` refused the connection on `127.0.0.1:9455` (`@@D-736`).
            resolution: {impl: 'kubernetes'},
            // Every process of the deployment sends its records to the `viewer` realm, at the name
            // its port is published under: the realm contributes the UDP port and the tree turns it
            // into a Service of the realm's own name, in every profile (`@@D-950`). A suite that
            // leaves the realm out of a tree drops the block with it.
            log: {destination: {host: 'viewer', port: 9999}},
            gateway: {
                static: {root: '/opt/deploy/suite/suite/blong-suite/dist'},
            },
            // No realm is named here, and that is the point: a *deployed* process loads the realms its
            // own layer flags name (`--<realm>.<layer>`, one flag per selector its plan split on) and
            // not the whole suite — the pod has to start fast and carry only what it serves (T-265).
            // What this block carries is what a release shares: the cluster's own values.
            srv: {
                db: {
                    knex: {
                        connection: {
                            // Host and port are named here rather than left to the adapter's own
                            // `release` defaults, because the merge at a connection object is not
                            // deep enough to keep them: whatever block is merged last *is* the
                            // connection, so a suite that names only the credentials hands knex a
                            // connection with no host and the process dials `127.0.0.1:3306`. The
                            // migration Job failed exactly that way on the first release-only
                            // deployment (F-414).
                            host: 'db',
                            port: 3306,
                            // The pair comes from the tenant's own file, not from a source tree
                            // (`@@D-857`): Secret `blong-releaserc-etc`, mounted at
                            // `/etc/blong_releaserc` and merged by `rc`. `blong-secrets` is the
                            // operator's and carries only what it generates (`@@D-855`). A database the
                            // tree brings along still creates its own users from its own Secret, which is
                            // why the `mysql` service below asks for `credentials.generate`.
                            database: 'blong-integration',
                        },
                    },
                },
            },
        },
        // A planning run has to see every realm the suite can deploy: the tree *is* the set of
        // processes those realms become, so a realm missing here is a realm missing from the tree.
        // Every suite names its realms once per intent that has to know them — `dev` for a
        // developer's run, `k8s` for the tree, and the flags for a deployed process.
        k8s: {core: {}, access: {}, marine: {}, login: {}, viewer: {}},
        // A migration names the realms here for the same reason a planning run does: bringing a
        // database up to date means *every* realm the suite declares, and no intent implies a realm
        // from another. What such a run needs of each realm is the realm's own answer — `upgrade`
        // activates `error`, `adapter` and `orchestrator` in `core/blong-lib/layers.ts`, and a realm
        // that needs more says so in its own `layer.server.ts` — so the generated Job carries no
        // `--<realm>.<layer>` selector at all (T-268).
        upgrade: {core: {}, access: {}, marine: {}, login: {}, viewer: {}},
        dev: {
            srv: {
                db: {
                    // logLevel: 'debug',
                },
            },
            core: {},
            access: {},
            marine: {},
            login: {},
            // The receiver rides this process in dev, and a process nobody names a destination for
            // sends its records to the realm beside it — so a run from source names the realm and
            // nothing about the address (`@@D-953`).
            viewer: {},
        },
        // `blong <entry> k8s` needs no block of its own now: the deploy settings above are what the
        // generator reads, and the realm's own `k8s` activation block is what tells it to write. The
        // artifact is fetched by the fill Job, so its URL has to be one the nodes can
        // reach, and the image is built and imported into the cluster.
        // What the deployed pods run, and the settings a release shares with every other release, is
        // the `release` block above. There is deliberately no `microservice` block left: the resolver
        // and the in-process dispatch are the framework's own `release` defaults now
        // (`core/blong-gogo/src/load.ts`), the database's shape belongs to the adapter that owns it
        // (`core/blong-server/adapter/db.ts`), and what remains is the cluster's — which is what
        // `release` holds.
        //
        // No `kustomize` key there on purpose: an empty one would replace the `default` block rather
        // than add to it, and the deploy settings above are what this process reconciles from.
    },
}));