-
Notifications
You must be signed in to change notification settings - Fork 0
feat(ssr-sidecar): add a Node 24 HTML embed sidecar #292
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| --- | ||
| "@mapsight/ssr-sidecar": minor | ||
| --- | ||
|
|
||
| Add a Node 24 HTML embed sidecar with `/health`, `/v1/render`, and `/purge`. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| * | ||
| !package.json | ||
| !dist |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| dist/ |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| FROM node:24-bookworm-slim | ||
|
|
||
| WORKDIR /app | ||
|
|
||
| COPY package.json ./ | ||
| COPY dist ./dist | ||
|
|
||
| USER node | ||
|
|
||
| ENV HOME=/tmp | ||
| ENV MAPSIGHT_SSR_HOST=0.0.0.0 | ||
| ENV MAPSIGHT_SSR_PORT=4123 | ||
| ENV MAPSIGHT_SSR_MODULE=/app/dist/render.js | ||
|
|
||
| EXPOSE 4123 | ||
|
|
||
| HEALTHCHECK --interval=10s --timeout=3s --start-period=10s --retries=5 \ | ||
| CMD ["node", "-e", "fetch('http://127.0.0.1:4123/health').then((r)=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"] | ||
|
|
||
| CMD ["node", "dist/server.js"] |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,85 @@ | ||
| # @mapsight/ssr-sidecar | ||
|
|
||
| Generic Node 24 HTTP process for Mapsight HTML embed SSR. | ||
|
|
||
| Hosts pull `ghcr.io/open-mapsight/ssr-sidecar` and bind-mount their product | ||
| `render.js`. The image ships only this process plus a contract stub — never a | ||
| host bundle. | ||
|
|
||
| npm `@mapsight/ssr-sidecar` is how the image is built and tested. Host stacks | ||
| pull the image; they do not `pnpm add` this package. | ||
|
|
||
| The current dist-tag is **`beta`**. | ||
|
|
||
| ## Public contract | ||
|
|
||
| | Method | Path | Response | | ||
| | ------ | ------------ | -------------------------------------------- | | ||
| | `GET` | `/health` | `ok` | | ||
| | `POST` | `/v1/render` | JSON `{ v: 1, html, state, pageMeta, meta }` | | ||
| | `POST` | `/purge` | JSON `string[]` of deleted cache keys | | ||
|
|
||
| There is no `POST /render`. Unknown routes return `404`. | ||
|
|
||
| `POST /v1/render` accepts: | ||
|
|
||
| ```json | ||
| { | ||
| "preset": "simpleMap", | ||
| "options": { | ||
| "containerId": "mapsight-embed-1" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Errors are `{ v: 1, error: { code, message } }` with `VALIDATION`, | ||
| `BODY_TOO_LARGE`, `RENDER_FAILED`, or `RENDER_TIMEOUT`. | ||
|
|
||
| `POST /purge` accepts `{ "urls": ["https://…/file.geojson"] }` or `{}` / no | ||
| `urls` to clear all. | ||
|
|
||
| Keep the process off public ingress. | ||
|
|
||
| ## Image | ||
|
|
||
| ```bash | ||
| docker pull ghcr.io/open-mapsight/ssr-sidecar:beta | ||
| ``` | ||
|
|
||
| Bind-mount the host `dist-ssr` and point at the product module: | ||
|
|
||
| ```yaml | ||
| services: | ||
| ssr: | ||
| image: ghcr.io/open-mapsight/ssr-sidecar:beta | ||
| environment: | ||
| MAPSIGHT_SSR_MODULE: /host/render.js | ||
| volumes: | ||
| - ${LOCAL_SSR_MOUNT}:/host:ro | ||
| ports: | ||
| - "127.0.0.1:4123:4123" | ||
| ``` | ||
|
|
||
| The stub module at `/app/dist/render.js` is the default when nothing is mounted. | ||
|
|
||
| ## Environment | ||
|
|
||
| | Variable | Role | | ||
| | ----------------------------------------- | ------------------------------------------------------------------------------ | | ||
| | `MAPSIGHT_SSR_HOST` | Bind address (default `0.0.0.0`) | | ||
| | `MAPSIGHT_SSR_PORT` | Bind port (default `4123`) | | ||
| | `MAPSIGHT_SSR_MODULE` | ESM module exporting `render()` (and optionally `renderEnvelope()`, `purge()`) | | ||
| | `MAPSIGHT_SSR_AWAIT_TIMEOUT_MS` | Read by the product module, not this server | | ||
| | `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` | Installed via `http.setGlobalProxyFromEnv` | | ||
| | `MAPSIGHT_SSR_HTTP_ORIGINS` | Comma hosts rewritten `https` → `http` for hairpin fetches | | ||
|
|
||
| ## Develop | ||
|
|
||
| ```bash | ||
| pnpm --filter @mapsight/ssr-sidecar test | ||
| pnpm --filter @mapsight/ssr-sidecar typecheck | ||
| pnpm --filter @mapsight/ssr-sidecar build | ||
| ``` | ||
|
|
||
| Hydration contract: | ||
| [SSR and state hydration](https://github.com/open-mapsight/mapsight/blob/main/docs/integration/SSR_HYDRATION.md). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| import {defineConfig} from "eslint/config"; | ||
|
|
||
| import baseConfig, { | ||
| testFilesEslintConfig, | ||
| } from "../../configs/eslint-config-base.mts"; | ||
|
|
||
| export default defineConfig([baseConfig, testFilesEslintConfig]); |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,42 @@ | ||
| { | ||
| "name": "@mapsight/ssr-sidecar", | ||
| "description": "Node 24 HTTP sidecar for Mapsight HTML embed SSR", | ||
| "version": "0.0.0", | ||
| "type": "module", | ||
| "bin": { | ||
| "mapsight-ssr-sidecar": "./dist/server.js" | ||
| }, | ||
| "devDependencies": { | ||
| "@types/node": "catalog:", | ||
| "typescript": "catalog:", | ||
| "vitest": "catalog:" | ||
| }, | ||
| "engines": { | ||
| "node": "^24.15.0" | ||
| }, | ||
| "exports": { | ||
| ".": { | ||
| "types": "./dist/index.d.ts", | ||
| "import": "./dist/index.js" | ||
| } | ||
| }, | ||
| "files": [ | ||
| "dist" | ||
| ], | ||
| "license": "MIT", | ||
| "publishConfig": { | ||
| "access": "public", | ||
| "tag": "beta" | ||
| }, | ||
| "repository": { | ||
| "url": "https://github.com/open-mapsight/mapsight" | ||
| }, | ||
| "scripts": { | ||
| "build": "tsc --project tsconfig.build.json", | ||
| "clean": "rm -rf dist", | ||
| "clean-build": "npm-run-all clean build", | ||
| "lint": "eslint", | ||
| "test": "vitest run", | ||
| "typecheck": "tsc --noEmit" | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,24 @@ | ||
| export { | ||
| defaultRenderModulePath, | ||
| startSsrSidecar, | ||
| type SsrSidecarListen, | ||
| type SsrSidecarOptions, | ||
| } from "./server.ts"; | ||
| export {purge, render, renderEnvelope} from "./render.ts"; | ||
| export type {PlacePageMeta, SsrEnvelope, SsrRequestBody} from "./render.ts"; | ||
| export { | ||
| extractStateFromFragment, | ||
| normalizeRenderResult, | ||
| type SsrRenderResult, | ||
| type SsrV1Error, | ||
| type SsrV1ErrorCode, | ||
| type SsrV1Success, | ||
| } from "./v1.ts"; | ||
| export {parsePurgeUrls, runPurge, type PurgeFn} from "./purge.ts"; | ||
| export { | ||
| httpOriginHostsFromEnv, | ||
| installEnvHttpProxyDispatcher, | ||
| installHttpsOriginRewrite, | ||
| proxyUrlFromEnv, | ||
| rewriteHttpsToHttpOrigin, | ||
| } from "./proxy.ts"; |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.