fix(platformservice): Update dependency versions and refactor import paths for improved compatibility; add initial DcRouter plan documentation.

changelog.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 2025-05-04 - 2.3.1 - fix(platformservice)
+Update dependency versions and refactor import paths for improved compatibility; add initial DcRouter plan documentation.
+
+- Upgrade @git.zone/tsbuild to ^2.3.2 and @push.rocks/tapbundle to ^6.0.3.
+- Upgrade @api.global/typedserver to ^3.0.74 and update related API dependencies (cloudflare, letterxpress).
+- Upgrade smartdata to ^5.15.1, add smartdns (^6.2.2), upgrade smartproxy to ^10.0.2, smartrequest to ^2.1.0, smartrule to ^2.0.1, and smartrx to ^3.0.10.
+- Upgrade @serve.zone/interfaces to ^5.0.4 and @tsclass/tsclass to ^9.1.0; update mailauth to ^4.8.4.
+- Add packageManager field in package.json for PNPM configuration.
+- Add readme.plan.md detailing the DcRouter implementation plan.
+- Refactor import paths in several TS files (e.g. ts/plugins.ts, ts/mta classes) for consistency.
+
 ## 2025-03-15 - 2.3.0 - feat(platformservice)
 Add AIBridge module and refactor service file paths for improved module organization
 

package.json

@@ -16,35 +16,36 @@
     "localPublish": ""
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^2.1.17",
+    "@git.zone/tsbuild": "^2.3.2",
     "@git.zone/tsrun": "^1.2.8",
     "@git.zone/tstest": "^1.0.88",
     "@git.zone/tswatch": "^2.0.1",
-    "@push.rocks/tapbundle": "^5.0.22"
+    "@push.rocks/tapbundle": "^6.0.3"
   },
   "dependencies": {
     "@api.global/typedrequest": "^3.0.19",
-    "@api.global/typedserver": "^3.0.27",
+    "@api.global/typedserver": "^3.0.74",
     "@api.global/typedsocket": "^3.0.0",
-    "@apiclient.xyz/cloudflare": "^6.0.3",
+    "@apiclient.xyz/cloudflare": "^6.4.1",
-    "@apiclient.xyz/letterxpress": "^1.0.20",
+    "@apiclient.xyz/letterxpress": "^1.0.22",
     "@push.rocks/projectinfo": "^5.0.1",
     "@push.rocks/qenv": "^6.0.5",
-    "@push.rocks/smartdata": "^5.0.7",
+    "@push.rocks/smartdata": "^5.15.1",
+    "@push.rocks/smartdns": "^6.2.2",
     "@push.rocks/smartfile": "^11.0.4",
     "@push.rocks/smartlog": "^3.0.3",
     "@push.rocks/smartmail": "^1.0.24",
     "@push.rocks/smartpath": "^5.0.5",
     "@push.rocks/smartpromise": "^4.0.3",
-    "@push.rocks/smartproxy": "^4.1.0",
+    "@push.rocks/smartproxy": "^10.0.2",
-    "@push.rocks/smartrequest": "^2.0.21",
+    "@push.rocks/smartrequest": "^2.1.0",
     "@push.rocks/smartrule": "^2.0.1",
-    "@push.rocks/smartrx": "^3.0.7",
+    "@push.rocks/smartrx": "^3.0.10",
     "@push.rocks/smartstate": "^2.0.0",
-    "@serve.zone/interfaces": "^4.12.1",
+    "@serve.zone/interfaces": "^5.0.4",
-    "@tsclass/tsclass": "^5.0.0",
+    "@tsclass/tsclass": "^9.1.0",
     "@types/mailparser": "^3.4.5",
-    "mailauth": "^4.6.5",
+    "mailauth": "^4.8.4",
     "mailparser": "^3.6.9",
     "uuid": "^11.1.0"
   },
@@ -76,5 +77,6 @@
       "mongodb-memory-server",
       "puppeteer"
     ]
-  }
+  },
+  "packageManager": "pnpm@10.7.0+sha512.6b865ad4b62a1d9842b61d674a393903b871d9244954f652b8842c2b553c72176b278f64c463e52d40fff8aba385c235c8c9ecf5cc7de4fd78b8bb6d49633ab6"
 }

readme.plan.md

@@ -0,0 +1,91 @@
+ # DcRouter Implementation Plan
+
+ This document outlines the plan for developing **DcRouter**, a central routing
+ component for the platform service. DcRouter will provide:
+   - HTTP/HTTPS reverse proxy with TLS (ACME) support
+   - TCP/SNI-based proxying
+   - Mail Transfer Agent (MTA) for inbound/outbound SMTP
+   - Rule-based routing for web and mail traffic
+   - DNS-based dynamic routing
+   - Configuration, persistence, logging, and monitoring
+
+ ## 1. Read and Summarize Dependencies
+ We will leverage existing modules; key points from their READMEs:
+ - **@push.rocks/smartproxy**: high-performance HTTP/HTTPS reverse proxy,
+   TLS termination, ACME HTTP-01, WebSockets, low-level port forwarding (nftables),
+   TCP/SNI proxy with dynamic routing and IP filtering.
+ - **@push.rocks/smartmail**: unified mail data structures and utilities.
+ - **mailparser**: parse raw SMTP messages into structured objects.
+ - **mailauth**: SPF/DKIM/DMARC validation and signing (DKIM).
+ - **@api.global/typedserver** / **typedsocket**: typed HTTP and TCP server abstractions.
+ - **@push.rocks/smartrule**: rule engine for dynamic decision-making on traffic.
+ - **@push.rocks/smartdns**: DNS resolution and caching for routing decisions.
+ - **@push.rocks/smartdata**: persistent key/value or document store for configs.
+ - **@push.rocks/smartlog** and **@push.rocks/smartrx**: logging and metrics/event tracking.
+ - **@push.rocks/qenv**: environment-based configuration loading.
+ - **ts/mta**: built-in MTA implementation (MtaService, SMTPServer, EmailSendJob, DKIMCreator/Verifier, DNSManager, ApiManager, Email class).
+
+ ## 2. High-Level Architecture
+ DcRouter will instantiate and coordinate:
+ 1. **HTTP(S) Proxy Layer**
+    - Use `NetworkProxy` and `Port80Handler` from smartproxy
+    - Manage virtual hosts, certificates, redirects
+ 2. **TCP/SNI Proxy Layer (SmartProxy)**
+    - Use `SmartProxy` from `@push.rocks/smartproxy` to:
+      - Forward TCP connections by port or port ranges to backends (nftables-like port forwarding).
+      - Route TLS connections based on SNI to different target IPs/ports (SNI bridge).
+      - Integrate HTTP reverse proxy on select ports via `NetworkProxyBridge`.
+      - Manage ACME certificates with built-in `Port80Handler` and `CertProvisioner`.
+      - Apply IP filtering, connection rate limiting, timeouts, and detailed logging.
+ 3. **SMTP/MTA Layer**
+    - Leverage `MtaService` from `ts/mta`, coordinating subcomponents:
+      - `SMTPServer` (classes.smtpserver): SMTP listener on ports 25/587 with STARTTLS/TLS
+      - `Email` and `EmailSendJob`: queue-based outbound sending with retries and rate limiting
+      - `DKIMCreator` / `DKIMVerifier`: automatic key management, signing, and verification
+      - `DNSManager`: generate and update DNS records for DKIM/SPF/MTA
+      - `ApiManager`: certificate provisioning and renewal via typedrequest/typedsocket
+    - Integrate inbound processing (mailparser, SPF/DKIM validation) and routing rules
+ 4. **Rule Engine**
+    - Use smartrule to define routing rules for HTTP domains and mail addresses
+    - Support wildcard matching, priority, and dynamic updates
+ 5. **DNS Integration**
+    - Use smartdns to resolve backend targets by name, with caching
+ 6. **Persistence & Config**
+    - Load environment config via qenv
+    - Store dynamic state (rules, domains, MTA settings) in smartdata
+ 7. **Logging & Metrics**
+    - Instrument all layers with smartlog and smartrx
+ 8. **Management API / CLI**
+    - Expose REST/CLI commands via typedserver for: add/remove domains, rules,
+      view status, reload config, etc.
+
+ ## 3. Feature Breakdown and Milestones
+ - [ ] A. Core Router scaffolding (`DcRouter` class)
+ - [ ] B. HTTP/HTTPS proxy integration
+ - [ ] C. SmartProxy Integration
+   - [ ] C1. Define `IPortProxySettings` with `fromPort`, `toPort`, `domainConfigs`, and global port ranges
+   - [ ] C2. Configure `domainConfigs` to mix port forwarding, SNI routing, and `useNetworkProxy` flags
+   - [ ] C3. Initialize and start `SmartProxy`, including `Port80Handler` for ACME and `CertProvisioner`
+   - [ ] C4. Wire SmartProxy events (e.g., certificate issuance, connection logging) into DcRouter
+   - [ ] C5. Support runtime updates to `domainConfigs` for dynamic routing changes
+ - [ ] D. MTA Integration (ts/mta)
+  - [ ] D1. Scaffold integration of `MtaService` into `DcRouter`
+  - [ ] D2. Configure and start `SMTPServer` with TLS/STARTTLS on ports 25/587
+  - [ ] D3. Wire inbound email handling via `processIncomingEmail` and rule engine
+  - [ ] D4. Implement outbound queue processing (`EmailSendJob`), retries, rate limiting
+  - [ ] D5. Manage DKIM keys and DNS records (`DKIMCreator`, `DNSManager`)
+  - [ ] D6. Provision and auto-renew certificates (`ApiManager`)
+ - [ ] E. Rule engine wiring for HTTP and SMTP
+ - [ ] F. DNS-based dynamic resolution
+ - [ ] G. Persistence layer for configs and state
+ - [ ] H. Logging/metrics instrumentation
+ - [ ] I. CLI and REST API endpoints
+ - [ ] J. Automated tests for each layer
+ - [ ] K. Documentation and examples in README
+
+ ## 4. Next Steps
+ 1. Review and refine this plan.
+ 2. Begin implementation starting with the core scaffolding (A).
+ 3. Iterate through features in milestone order.
+
+ _Last updated: 2025-05-04_

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/platformservice',
-  version: '2.3.0',
+  version: '2.3.1',
   description: 'A multifaceted platform service handling mail, SMS, letter delivery, and AI services.'
 }

ts/dcrouter/classes.dcrouter.ts

@@ -0,0 +1,49 @@
+import * as plugins from '../plugins.js';
+import * as paths from '../paths.js';
+
+import { type IMtaConfig, MtaService } from '../mta/classes.mta.js';
+
+export interface IDcRouterOptions {
+  portProxyConfig?: plugins.smartproxy.IPortProxySettings;
+  mtaConfig?: IMtaConfig;
+  dnsServerConfig?: plugins.smartdns.IDnsServerOptions;
+}
+
+/**
+ * DcRouter can be run on ingress and egress to and from a datacenter site.
+ */
+export class DcRouter {
+  private options: IDcRouterOptions;
+  public smartProxy: plugins.smartproxy.SmartProxy;
+  public mta: MtaService;
+  public dnsServer: plugins.smartdns.DnsServer;
+  constructor(optionsArg: IDcRouterOptions) {
+    this.options = optionsArg;
+    if (this.options.portProxyConfig) {
+      this.smartProxy = new plugins.smartproxy.SmartProxy(this.options.portProxyConfig);
+    }
+    if (this.options.mtaConfig) {
+      this.mta = new MtaService(null, this.options.mtaConfig);
+    }
+  }
+
+  public async start() {
+    if (this.smartProxy) {
+      await this.smartProxy.start();
+    }
+    if (this.mta) {
+      await this.mta.start();
+    }
+  }
+
+  public async stop() {
+    if (this.smartProxy) {
+      await this.smartProxy.stop();
+    }
+    if (this.mta) {
+      await this.mta.stop();
+    }
+  }
+}
+
+export default DcRouter;

ts/email/classes.apimanager.ts

@@ -61,7 +61,7 @@ export class ApiManager {
     );
 
     // Add endpoint to check email status
-    this.typedRouter.addTypedHandler<{ emailId: string }>(
+    this.typedRouter.addTypedHandler<plugins.servezoneInterfaces.platformservice.mta.IReq_CheckEmailStatus>(
       new plugins.typedrequest.TypedHandler('checkEmailStatus', async (requestData) => {
         // If MTA is enabled, use it to check status
         if (this.emailRef.mtaConnector) {
@@ -78,7 +78,7 @@ export class ApiManager {
     );
 
     // Add statistics endpoint
-    this.typedRouter.addTypedHandler<void>(
+    this.typedRouter.addTypedHandler<plugins.servezoneInterfaces.platformservice.mta.IReq_GetEMailStats>(
       new plugins.typedrequest.TypedHandler('getEmailStats', async () => {
         return this.emailRef.getStats();
       })

ts/mta/classes.dnsmanager.ts

@@ -1,6 +1,6 @@
 import * as plugins from '../plugins.js';
 import * as paths from '../paths.js';
-import type { MtaService } from './mta.classes.mta.js';
+import type { MtaService } from './classes.mta.js';
 
 /**
  * Interface for DNS record information

ts/mta/classes.emailsignjob.ts

@@ -1,5 +1,5 @@
 import * as plugins from '../plugins.js';
-import type { MtaService } from './mta.classes.mta.js';
+import type { MtaService } from './classes.mta.js';
 
 interface Headers {
   [key: string]: string;

ts/plugins.ts

@@ -41,6 +41,7 @@ export {
 import * as projectinfo from '@push.rocks/projectinfo';
 import * as qenv from '@push.rocks/qenv';
 import * as smartdata from '@push.rocks/smartdata';
+import * as smartdns from '@push.rocks/smartdns';
 import * as smartfile from '@push.rocks/smartfile';
 import * as smartlog from '@push.rocks/smartlog';
 import * as smartmail from '@push.rocks/smartmail';
@@ -51,7 +52,7 @@ import * as smartrequest from '@push.rocks/smartrequest';
 import * as smartrule from '@push.rocks/smartrule';
 import * as smartrx from '@push.rocks/smartrx';
 
-export { projectinfo, qenv, smartdata, smartfile, smartlog, smartmail, smartpath, smartproxy, smartpromise, smartrequest, smartrule, smartrx };
+export { projectinfo, qenv, smartdata, smartdns, smartfile, smartlog, smartmail, smartpath, smartproxy, smartpromise, smartrequest, smartrule, smartrx };
 
 // apiclient.xyz scope
 import * as letterxpress from '@apiclient.xyz/letterxpress';