serve.zone/dcrouter
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(docs): refresh package readmes with clearer runtime, API client, interfaces, migrations, and dashboard guidance

Browse Source
This commit is contained in:
Jürgen Kunz
2026-04-17 13:43:13 +00:00
parent 1f25ca4095
commit c5ca95b6f5
9 changed files with 321 additions and 430 deletions
Download Patch File Download Diff File Expand all files Collapse all files

54
ts_migrations/readme.md
View File

@@ -1,53 +1,63 @@
# @serve.zone/dcrouter-migrations
Migration runner package for dcrouter's smartdata-backed persistence layer. 🧱
This package provides the startup migration chain that upgrades dcrouter data across releases before the application reads from the database.
Versioned SmartMigration chain for dcrouter's persistent data. This package builds the migration runner that dcrouter executes before DB-backed managers start reading collections.
## Issue Reporting and Security
For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
## Installation
```bash
pnpm add @serve.zone/dcrouter-migrations
```
## What It Exports
| Export | Purpose |
| --- | --- |
| `createMigrationRunner(db, targetVersion)` | Builds the dcrouter SmartMigration runner for the current application version |
| `IMigrationRunner` | Small interface describing the runner's `run()` method |
| `IMigrationRunResult` | Logged result shape used after execution |
| `createMigrationRunner(db, targetVersion)` | Builds the dcrouter migration runner for the target application version |
| `IMigrationRunner` | Small interface for the returned runner |
| `IMigrationRunResult` | Result shape logged after a run |
## When To Use It
- You are embedding dcrouter's storage layer outside the full runtime.
- You want to test or inspect schema transitions directly.
- You are extending dcrouter with new persistent data and need versioned upgrades.
If you boot the full `DcRouter` runtime, this package is already used for you during startup.
## Usage
```typescript
import { createMigrationRunner } from '@serve.zone/dcrouter-migrations';
const migration = await createMigrationRunner(db, '13.18.0');
const migration = await createMigrationRunner(db, '13.20.0');
const result = await migration.run();
console.log(result.currentVersionBefore, result.currentVersionAfter);
```
## What These Migrations Handle
## What the Current Chain Covers
The migration chain currently covers dcrouter-specific storage transitions such as:
- target profile target field migration from `host` to `ip`
- legacy domain source rename from `manual` to `dcrouter`
- legacy DNS record source rename from `manual` to `local`
- route storage unification from `StoredRouteDoc` to `RouteDoc`
- route `origin` backfill for migrated API routes
- `systemKey` backfill for persisted config, email, and DNS routes
- target profile target field renames
- domain and DNS record source renames
- route collection unification into `RouteDoc`
- persisted route metadata backfills such as `origin` and `systemKey`
## Authoring Rules
## Important Behavior
- fresh installs are stamped directly to the current target version
- migration steps are registered in strict version order
- migrations run before services load DB-backed state
- route-related migrations use smartdata collection names exactly as declared in code
If you are embedding dcrouter's DB layer outside the main runtime, run this package before any feature code assumes the latest schema.
- Add new migration logic only in `ts_migrations/index.ts`.
- Keep every step idempotent so reruns are safe.
- Make each step's `.to()` version line up with the release version that ships it.
- When adding new collection references, use the exact smartdata class-name collection casing for new code.
## License and Legal Information
This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license](../license) file.
This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](../license) file.
**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.