pockethost 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # pockethost
 
+## 1.6.0
+
+### Minor Changes
+
+- 40bbb3c: Improve tryFetch by accepting node-fetch params
+- 12f029a: Add changeset maker
+- b7277cf: Add public instance URL calculators and refactor HTTP protocol detection
+- 45a8f45: Add internal app (remote control) support
+- 55b43a1: Remove unneeded params from GetOrProvisionInstanceUrl filter
+- 5be2c9e: Initial commit
+- a236f3e: Added several more filters
+- 35edc77: Enhancement: actions execute sequentially
+- 879845a: Enhancement: unsubscribe from filters
+- c473ed9: Added support for priorities in actions
+- 795fcd7: New action: KillInstance
+- c32b845: Added support for Settings filter whereby all settings are collected and displayed in DEBUG() mode
+- cce72b3: New action: AfterPluginsLoaded
+- 82dde2d: Enhancement: filters now have extensible data types
+
+### Patch Changes
+
+- b55c585: Clean up dead code
+- 0e4bf43: Updated commit parser deps
+- f79b067: Added serve command details
+- dd3ceaa: Added filter debugging
+- 7931204: Fixed a bug where adding plugins was not saved correctly
+- 6e14f57: Updated plugin authoring guide
+- 7604930: Minor fix to GetOrProvisionInstanceUrl filter
+- 52b70cb: Fixed bug where --extra-plugins was not defaulting to '' correctly
+- Updated dependencies [c32b845]
+  - @pockethost/plugin-launcher-spawn@1.0.0
+  - @pockethost/plugin-auto-admin@1.0.0
+  - @pockethost/plugin-console-logger@1.0.0
+
 ## 1.5.0
 
 ### Minor Changes

package/changesetx.ts

@@ -0,0 +1,110 @@
+#!/usr/bin/env tsx
+import { execSync } from 'child_process'
+import { sync } from 'conventional-commits-parser'
+import fs, { readFileSync } from 'fs'
+import minimist from 'minimist'
+import { dirname, join } from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const repoRootDir = join(__dirname, `../..`)
+
+const argv = minimist(process.argv.slice(2))
+const commitMessage = argv._[0]!
+const { type, subject } = sync(commitMessage)
+if (!type) {
+  console.log('Invalid commit message type')
+  process.exit(1)
+}
+
+function getStagedPackageNames(filePaths: string[]): string[] {
+  const packageNames = new Set<string>()
+
+  filePaths.forEach((filePath) => {
+    const packageName = getPackageName(filePath)
+    if (packageName) {
+      packageNames.add(packageName)
+    }
+  })
+
+  return Array.from(packageNames)
+}
+
+function getPackageName(filePath: string): string | null {
+  const packagePath = filePath.split('/').slice(0, 2).join('/')
+  const packageJsonPath = join(repoRootDir, `${packagePath}/package.json`)
+  const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'))
+  try {
+    return packageJson.name
+  } catch (error) {
+    return null
+  }
+}
+
+function getStagedFileNames(): string[] {
+  const output = execSync('git diff --name-only --cached').toString()
+  const fileNames = output
+    .trim()
+    .split('\n')
+    .filter((fileName) => fileName.startsWith(`packages/`))
+  return fileNames
+}
+
+async function createChangesetFile() {
+  const fileNames = getStagedFileNames()
+  const packageNames = getStagedPackageNames(fileNames)
+
+  if (packageNames.length === 0) {
+    console.log('No packages staged for commit')
+    process.exit(0)
+  }
+  console.log('Staged packages:', packageNames)
+
+  const prefixMap = {
+    feat: 'minor',
+    enh: 'minor',
+    fix: 'patch',
+    docs: 'patch',
+    chore: 'patch',
+  } as const
+
+  if (!(type! in prefixMap)) {
+    console.log('Invalid prefix found in commit message')
+    process.exit(1)
+  }
+
+  const versionType = prefixMap[type as keyof typeof prefixMap]
+
+  const changesetFile = [
+    `---`,
+    ...packageNames.map((packageName) => `'${packageName}': ${versionType}`),
+    `---`,
+    ``,
+    subject,
+  ].join('\n')
+  return changesetFile
+}
+
+async function writeChangesetFile(changesetFile: string) {
+  const filePath = join(repoRootDir, `.changeset`, `${+new Date()}.md`)
+  try {
+    fs.writeFileSync(filePath, changesetFile)
+    console.log(`Changeset file written successfully at ${filePath}`)
+    execSync(`git add ${filePath}`)
+    console.log(`Changeset file added to git`)
+  } catch (error) {
+    console.error(`Error writing changeset file: ${error}`)
+  }
+}
+
+function commit() {
+  execSync(`git commit -m "${commitMessage}"`)
+}
+
+async function main() {
+  const changesetFile = await createChangesetFile()
+  await writeChangesetFile(changesetFile)
+  commit()
+}
+
+main()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pockethost",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "author": {
     "name": "Ben Allfree",
     "url": "https://github.com/benallfree"
@@ -41,19 +41,22 @@
     "typescript": "^5.4.5",
     "update-notifier": "^7.0.0",
     "url-pattern": "^1.0.3",
-    "@pockethost/plugin-auto-admin": "^0.1.1",
-    "@pockethost/plugin-console-logger": "^0.2.1",
-    "@pockethost/plugin-launcher-spawn": "^0.3.0"
+    "@pockethost/plugin-launcher-spawn": "^0.4.0",
+    "@pockethost/plugin-console-logger": "^0.3.0",
+    "@pockethost/plugin-auto-admin": "^0.2.0"
   },
   "devDependencies": {
+    "@types/conventional-commits-parser": "^5.0.0",
     "@types/express": "^4.17.21",
     "@types/http-proxy": "^1.17.13",
+    "@types/inquirer": "^9.0.7",
     "@types/json-stringify-safe": "^5.0.2",
     "@types/minimist": "^1.2.5",
     "@types/node": "^20.8.10",
     "@types/semver": "^7.5.4",
     "@types/tmp": "^0.2.5",
-    "@types/update-notifier": "^6.0.8"
+    "@types/update-notifier": "^6.0.8",
+    "conventional-commits-parser": "^5.0.0"
   },
   "scripts": {
     "check-types": "tsc --noEmit ",

package/readme.md

@@ -10,21 +10,75 @@ Extend PocketHost with its Plugin ecosystem. Start with the bare-bones dev serve
 
 ---
 
+<!-- @import "[TOC]" {cmd="toc" depthFrom=2 depthTo=2 orderedList=false} -->
+
+<!-- code_chunk_output -->
+
+- [Quickstart](#quickstart)
+- [Introduction](#introduction)
+- [The magic `serve` command](#the-magic-serve-command)
+- [Configuration](#configuration)
+- [Plugins Directory](#plugins-directory)
+- [Writing Plugins](#writing-plugins)
+- [Support](#support)
+
+<!-- /code_chunk_output -->
+
+---
+
 ## Quickstart
 
 ```
 npx pockethost serve
 ```
 
+## Introduction
+
+PocketHost is a multitenant PocketBase hosting system. With it, you can run multiple instances of PocketBase on different subdomains, all on the same server.
+
+Use PocketHost for development or production purposes.
+
+PocketHost can be easily extended using its thoughtful plugin architecture. By choosing additional plugins, PocketHost's features can be extended according to your exact needs. You can even write your own plugins.
+
+## The magic `serve` command
+
+`pockethost serve` is a special command that can be decorated with plugins. Plugins can respond to the `serve` command by running their own services.
+
+By convention, plugins that have some kind of `serve` functionality such as running a server, will make it available in two ways.
+
+The first way runs ONLY the plugin's `serve` functionality:
+
+```bash
+pockethost <plugin-name> serve
+```
+
+The second way runs ALL `serve` functionality from ALL plugins:
+
+```bash
+pockethost serve
+```
+
+The exact plugins can also be narrowed:
+
+```bash
+pockethost serve --only=plugin1,plugin2,plugin3
+```
+
+See the plugin authoring guide for more information on how to make a plugin that responds to both methods.
+
 ## Configuration
 
-PocketHost supports configuration by environment variable. All PocketHost environment variables begin with `PH_`.
+PocketHost supports configuration by environment variable, `.env` file, and also built-in settings via `pockethost config`.
+
+All PocketHost variables begin with `PH_`.
 
 PocketHost will search the current directory for an `.env` when it loads. Anything in `.env` will be merged with and override any `<PH_HOME>/.env` that may exist.
 
-Use `pockethost config` to set global defaults stored in `<PH_HOME>/.env`.
+Use `pockethost config` to list and set global defaults.
 
-### Variables
+### Core Variables
+
+See `pockethost config ls` for a full list of variables. Plugin variables will also be listed for loaded plugins.
 
 | Name           | Default                    | Discussion                                                                    |
 | -------------- | -------------------------- | ----------------------------------------------------------------------------- |
@@ -42,29 +96,32 @@ Use `pockethost config` to set global defaults stored in `<PH_HOME>/.env`.
 - `@pockethost/plugin-launcher-spawn`
 - `@pockethost/plugin-auto-admin`
 
-## Plugins
+## Plugins Directory
+
+PocketHost uses an action/filter architecture to support a growing list plugins. Some plugins have a CLI component, whereas others add purely programmatic support to alter how PocketHost works.
 
-PocketHost uses a hook architecture and features a growing list plugins. Some plugins have a CLI component, whereas others add purely programmatic support to alter how PocketHost works:
+### Core plugins
 
-Current plugins:
+These plugins are maintained by the PocketHost project.
 
-| name                             | description                                                                                       |
-| -------------------------------- | ------------------------------------------------------------------------------------------------- |
-| plugin-console-logger            | Routes log messages to the console                                                                |
-| plugin-auto-admin                | Auto-creates a default admin account on instance launch                                           |
-| plugin-launcher-spawn            | Launches PocketBase instances via `spawn()` on the local machine. PocketHost uses this by default |
-| plugin-cloudflare-request-logger | Log additional data when running behind Cloudflare                                                |
+| Name                                           | Description                                                                                                             |
+| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `@pockethost/plugin-console-logger`            | Routes log messages to the console                                                                                      |
+| `@pockethost/plugin-auto-admin`                | Auto-creates a default admin account on instance launch                                                                 |
+| `@pockethost/plugin-launcher-spawn`            | Launches PocketBase instances via `spawn()` on the local machine. PocketHost uses this by default                       |
+| `@pockethost/plugin-cloudflare-request-logger` | Log additional data when running behind Cloudflare                                                                      |
+| `@pockethost/plugin-ftp-server`                | Used to provide secure FTPS access to PocketBase instance data. This FTP server can run along-side a PocketHost server. |
 
 Coming soon:
 | name | description |
 | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| plugin-ftp-server | Used to provide secure FTPS access to PocketBase instance data. This FTP server can run along-side a PocketHost server. |
 | plugin-launcher-docker | Launches PocketBase instances via Docker. This is useful for running untrusted PocketBase code and instances. pockethost.io uses this. |
 | plugin-waf | A Web Application Firewall |
-| plugin-waf-enforce-ssl | Enforce SSL at the
-WAF
+| plugin-waf-enforce-ssl | Enforce SSL at the WAF
+
+## Writing Plugins
 
-See the [Plugin Authoring Guide](https://github.com/pockethost/pockethost/blob/master/packages/pockethost/plugin-guide.md) for details about what hooks and filters are available.
+See the [Plugin Authoring Guide](https://github.com/pockethost/pockethost/blob/master/packages/pockethost/plugin-guide.md) for details about how to write your own plugins.
 
 ## Support
 

package/src/cli/commands/ConfigCommand/index.ts

@@ -1,20 +1,5 @@
-import { forEach, keys, omit } from '@s-libs/micro-dash'
 import { Command } from 'commander'
-import { parse } from 'dotenv'
-import { existsSync, readFileSync, writeFileSync } from 'fs'
-import { info } from '../..'
-import { PH_HOME, isSettingKey, settings } from '../../../constants'
-
-const envFile = () => {
-  const envFile = PH_HOME(`.env`)
-  if (!existsSync(envFile)) {
-    writeFileSync(envFile, '')
-  }
-  return envFile
-}
-
-const _parse = () =>
-  parse(readFileSync(envFile(), { encoding: 'utf8' }).toString())
+import { listConfig, setConfig, unsetConfig } from '../../../core'
 
 export const ConfigCommand = () => {
   const cmd = new Command(`config`)
@@ -24,76 +9,20 @@ export const ConfigCommand = () => {
         .argument(`<name>`, `Config name`)
         .argument(`<value>`, `Config value`)
         .description(`Set a config value`)
-        .action((name, value) => {
-          if (!isSettingKey(name))
-            throw new Error(`Invalid setting name ${name}`)
-
-          if (value === '=') throw new Error(`Invalid value ${value}`)
-
-          const values = _parse()
-          values[name] = value
-          writeFileSync(
-            envFile(),
-            Object.entries(values)
-              .map(([k, v]) => `${k}=${v}`)
-              .join('\n'),
-          )
-          info(`Set ${name}=${value}`)
-          info(`Written to ${envFile()}`)
-        }),
+        .action(setConfig),
     )
 
     .addCommand(
       new Command(`unset`)
         .argument(`<name>`, `Config name`)
         .description(`Unset a config value`)
-        .action((name) => {
-          if (!isSettingKey(name))
-            throw new Error(`Invalid setting name ${name}`)
-
-          const values = _parse()
-          delete values[name]
-          writeFileSync(
-            envFile(),
-            Object.entries(values)
-              .map(([k, v]) => `${k}=${v}`)
-              .join('\n'),
-          )
-          info(`Unset ${name}`)
-          info(`Written to ${envFile()}`)
-        }),
+        .action(unsetConfig),
     )
     .addCommand(
       new Command(`list`)
         .description(`List all config values`)
         .alias(`ls`)
-        .action(() => {
-          const values = _parse()
-
-          if (keys(values).length > 0) {
-            info()
-            info(`Config values from ${envFile()}:`)
-            forEach(values, (v, k) => {
-              info(`\t${k}=${v}`)
-            })
-            info()
-          } else {
-            info(`No config values found in ${envFile()}`)
-          }
-
-          const defaults = omit(settings, keys(values) as any)
-          if (keys(defaults).length > 0) {
-            info(`Default values:`)
-            forEach(settings, (v, k) => {
-              if (k in values) return
-              info(`\t${k}=${v}`)
-            })
-          } else {
-            info(
-              `No default values because all values are defined in ${envFile()}`,
-            )
-          }
-        }),
+        .action(listConfig),
     )
   return cmd
 }

package/src/cli/commands/PluginCommand/index.ts

@@ -1,22 +1,10 @@
-import { uniq } from '@s-libs/micro-dash'
 import { Command } from 'commander'
-import { parse } from 'dotenv'
-import { existsSync, readFileSync, writeFileSync } from 'fs'
+import { readFileSync } from 'fs'
 import { error, info } from '../..'
-import { PH_HOME, PH_PLUGINS, PH_PROJECT_DIR } from '../../../constants'
+import { PH_PLUGINS, PH_PROJECT_DIR } from '../../../constants'
+import { appendConfig, filterConfig } from '../../../core'
 import { getCompatibleVersions, getPackageJson, removePackage } from './util'
 
-const envFile = () => {
-  const envFile = PH_HOME(`.env`)
-  if (!existsSync(envFile)) {
-    writeFileSync(envFile, '')
-  }
-  return envFile
-}
-
-const _parse = () =>
-  parse(readFileSync(envFile(), { encoding: 'utf8' }).toString())
-
 export const PluginCommand = () => {
   const cmd = new Command(`plugin`)
     .description(`Manage PocketHost plugins`)
@@ -33,22 +21,7 @@ export const PluginCommand = () => {
             const { version } = pkg
             await getCompatibleVersions(`pockethost`, version, [name])
 
-            const values = _parse()
-            values[`PH_PLUGINS`] = uniq([
-              ...(values[`PH_PLUGINS`]
-                ?.split(/,/)
-                .map((v) => v.trim())
-                .filter((v) => !!v) || []),
-              name,
-            ]).join(`,`)
-            writeFileSync(
-              envFile(),
-              Object.entries(values)
-                .map(([k, v]) => `${k}=${v}`)
-                .join('\n'),
-            )
-            info(`Installed ${name}`)
-            info(`Written to ${envFile()}`)
+            appendConfig(`PH_PLUGINS`, name)
           } catch (e) {
             error(`${e}`)
           }
@@ -81,21 +54,7 @@ export const PluginCommand = () => {
         .action(async (name) => {
           try {
             await removePackage(name)
-            const values = _parse()
-            values[`PH_PLUGINS`] = uniq([
-              ...(values[`PH_PLUGINS`]
-                ?.split(/,/)
-                .map((v) => v.trim())
-                .filter((v) => v !== name) || []),
-            ]).join(`,`)
-            writeFileSync(
-              envFile(),
-              Object.entries(values)
-                .map(([k, v]) => `${k}=${v}`)
-                .join('\n'),
-            )
-            info(`Removed ${name}`)
-            info(`Written to ${envFile()}`)
+            filterConfig(`PH_PLUGINS`, name)
           } catch (e) {
             error(`${e}`)
           }

package/src/cli/index.ts

@@ -10,6 +10,7 @@ import {
   DEBUG,
   LogLevelName,
   LoggerService,
+  doAfterPluginsLoadedAction,
   doCliCommandsFilter,
   loadPlugins,
 } from '../common'
@@ -36,13 +37,17 @@ export const main = async () => {
 
   const argv = minimist<{ e: string }>(process.argv.slice(2), {
     alias: { e: 'extra-plugins' },
+    default: { e: '' },
   })
   const extraPlugins = argv.e
     .split(/,/)
     .map((s) => s.trim())
     .filter((v) => !!v)
+
   await loadPlugins([pockethost, ...uniq(PH_PLUGINS()), ...extraPlugins])
 
+  await doAfterPluginsLoadedAction()
+
   program
     .name('pockethost')
     .description('Multitenant PocketBase hosting')

package/src/common/plugin/action.ts

@@ -1,9 +1,12 @@
+import { uniqueId } from '@s-libs/micro-dash'
 import { Express, Request, Response } from 'express'
+import { dbg } from '../../cli'
 import { LogLevelName } from '../Logger'
 import { DEBUG } from '../debug'
 import { InstanceFields } from '../schema'
 
 enum CoreActions {
+  AfterPluginsLoaded = 'core_after_plugins_loaded',
   Init = 'core_init',
   Serve = 'core_serve',
   AppMounted = 'core_on_app_mount',
@@ -18,6 +21,8 @@ enum CoreActions {
   BeforeInstanceStarted = 'core_before_instance_started',
   AfterInstanceStarted = 'core_after_instance_started',
 
+  KillInstance = 'core_kill_instance',
+
   BeforeInstanceStopped = 'core_before_instance_stopped',
   AfterInstanceStopped = 'core_after_instance_stopped',
 
@@ -27,20 +32,34 @@ enum CoreActions {
   Request = 'core_edge_request',
 }
 
-const actions: {
-  [key: string]: ActionHandler<any>[]
-} = {}
-
 export type ActionHandler<TContext = {}> = (
   context: TContext extends never ? [] : TContext,
 ) => Promise<void>
 
-async function registerAction(
+interface Action {
+  priority: number
+  handler: ActionHandler<any>
+}
+
+const actions: {
+  [key: string]: Action[]
+} = {}
+
+function registerAction(
   action: string,
   handler: (...args: any[]) => Promise<void>,
-) {
+  priority: number = 10,
+): () => void {
   if (!(action in actions)) actions[action] = []
-  actions[action]!.push(handler)
+  const uid = uniqueId(`a:${action}:`)
+  dbg(`${uid}:subscribe`)
+  actions[action]!.push({ priority, handler })
+  actions[action]!.sort((a, b) => a.priority - b.priority)
+
+  return () => {
+    dbg(`${uid}:unsubscribe`)
+    actions[action] = actions[action]!.filter((a) => a.handler !== handler)
+  }
 }
 
 async function action(actionName: string, context: any) {
@@ -49,7 +68,9 @@ async function action(actionName: string, context: any) {
   }
   const action = actions[actionName]
   if (!action) return false
-  await Promise.all(action.map((handler) => handler(context)))
+  for (const { handler } of action) {
+    await handler(context)
+  }
   return true
 }
 
@@ -58,18 +79,22 @@ export function createCustomActionWithContext<TContext extends {}>(
 ) {
   return [
     async (context: TContext) => action(actionName, context),
-    async (handler: ActionHandler<TContext>) =>
-      registerAction(actionName, handler),
+    (handler: ActionHandler<TContext>, priority = 10) =>
+      registerAction(actionName, handler, priority),
   ] as const
 }
 
 export function createCustomAction(actionName: CoreActions) {
   return [
     async () => action(actionName, {}),
-    async (handler: ActionHandler) => registerAction(actionName, handler),
+    (handler: ActionHandler, priority = 10) =>
+      registerAction(actionName, handler, priority),
   ] as const
 }
 
+export const [doAfterPluginsLoadedAction, onAfterPluginsLoadedAction] =
+  createCustomAction(CoreActions.AfterPluginsLoaded)
+
 export const [doRequestErrorAction, onRequestErrorAction] =
   createCustomActionWithContext<{
     err: Error
@@ -92,7 +117,9 @@ export const [doInstanceLogAction, onInstanceLogAction] =
   }>(CoreActions.InstanceLog)
 
 export const [doAppMountedAction, onAppMountedAction] =
-  createCustomActionWithContext<{ app: Express }>(CoreActions.AppMounted)
+  createCustomActionWithContext<{ app: Express; internalApp: Express }>(
+    CoreActions.AppMounted,
+  )
 
 export const [doIncomingRequestAction, onIncomingRequestAction] =
   createCustomActionWithContext<{ req: Request; res: Response; host: string }>(
@@ -117,6 +144,11 @@ export const [doAfterInstanceStartedAction, onAfterInstanceStartedAction] =
     CoreActions.AfterInstanceStarted,
   )
 
+export const [doKillInstanceAction, onKillInstanceAction] =
+  createCustomActionWithContext<{ instance: InstanceFields }>(
+    CoreActions.KillInstance,
+  )
+
 export const [doBeforeInstanceStoppedAction, onBeforeInstanceStoppedAction] =
   createCustomActionWithContext<{ instance: InstanceFields; url: string }>(
     CoreActions.BeforeInstanceStopped,

package/src/common/plugin/filter.ts

@@ -2,13 +2,18 @@ import { Command } from 'commander'
 import { Request, Response } from 'express'
 import { DEBUG } from '../debug'
 import { InstanceFields, InstanceId } from '../schema'
+import { UserId } from '../schema/BaseFields'
 
 export enum CoreFilters {
+  Settings = 'core_settings',
   CliCommands = 'core_cli_commands',
   ServeSlugs = 'core_serve_slugs',
   SpawnConfig = 'core_spawn_config',
+  AuthenticateUser = 'core_authenticate_user',
   GetInstanceByRequestInfo = 'core_get_instance_by_request_info',
   GetInstanceById = 'core_get_instance_by_id',
+  GetOneInstanceByExactCriteria = 'core_get_one_instance_by_exact_criteria',
+  GetAllInstancesByExactCriteria = 'core_get_all_instances_by_exact_criteria',
   InstanceConfig = 'core_instance_config',
   ErrorSpawningInstanceMessage = 'core_error_spawning_instance_message',
   FailedToLaunchInstanceMessage = 'core_failed_to_launch_instance_message',
@@ -17,6 +22,7 @@ export enum CoreFilters {
   GetOrProvisionInstanceUrl = 'core_get_or_provision_instance_url',
   PocketBaseLaunchHandler = 'core_pocket_base_launch_handler',
   NewInstanceRecord = 'core_new_instance_record',
+  IsInstanceRunning = 'core_is_instance_running',
 }
 
 export type FilterHandler<TCarry, TContext> = (
@@ -31,14 +37,23 @@ const filters: {
   [key: string]: FilterEntry<any>[]
 } = {}
 
-async function registerFilter<TCarry, TContext extends {} = {}>(
+function registerFilter<TCarry, TContext extends {} = {}>(
   filter: string,
   handler: FilterHandler<TCarry, TContext>,
   priority = 10,
-) {
+): () => void {
   if (!(filter in filters)) filters[filter] = []
   filters[filter]!.push({ priority, handler })
   filters[filter]!.sort((a, b) => a.priority - b.priority)
+
+  return () => {
+    const index = filters[filter]!.findIndex(
+      (entry) => entry.handler === handler,
+    )
+    if (index !== -1) {
+      filters[filter]!.splice(index, 1)
+    }
+  }
 }
 
 async function filter<TCarry, TContext extends {} = {}>(
@@ -53,7 +68,14 @@ async function filter<TCarry, TContext extends {} = {}>(
   if (!filter) return initialValue
   return filter.reduce(
     (carry, entry) =>
-      carry.then((carryRes) => entry.handler(carryRes, context)),
+      carry
+        .then((carryRes) => entry.handler(carryRes, context))
+        .then((carryRes) => {
+          if (DEBUG()) {
+            console.log(`f:${filterName}`, carryRes, context)
+          }
+          return carryRes
+        }),
     Promise.resolve(initialValue),
   ) as TCarry
 }
@@ -64,8 +86,15 @@ function createCustomFilterWithContext<TCarry, TContext extends {} = {}>(
   return [
     async (initialValue: TCarry, context: TContext) =>
       filter<TCarry, TContext>(filterName, initialValue, context),
-    async (handler: FilterHandler<TCarry, TContext>, priority = 10) =>
-      registerFilter<TCarry, TContext>(filterName, handler, priority),
+    async <TExtraCarry = unknown>(
+      handler: FilterHandler<TCarry & TExtraCarry, TContext>,
+      priority = 10,
+    ) =>
+      registerFilter<TCarry & TExtraCarry, TContext>(
+        filterName,
+        handler,
+        priority,
+      ),
   ] as const
 }
 
@@ -73,11 +102,24 @@ function createCustomFilter<TCarry>(filterName: string) {
   return [
     async (initialValue: TCarry) =>
       filter<TCarry>(filterName, initialValue, {}),
-    async (handler: FilterHandler<TCarry, {}>, priority = 10) =>
-      registerFilter<TCarry, {}>(filterName, handler, priority),
+    async <TExtraCarry = unknown>(
+      handler: FilterHandler<TCarry & TExtraCarry, {}>,
+      priority = 10,
+    ) =>
+      registerFilter<TCarry & TExtraCarry, {}>(filterName, handler, priority),
   ] as const
 }
 
+export const [doSettingsFilter, onSettingsFilter] = createCustomFilter<{
+  [_: string]: any
+}>(CoreFilters.Settings)
+
+export const [doAuthenticateUserFilter, onAuthenticateUserFilter] =
+  createCustomFilterWithContext<
+    UserId | undefined,
+    { username: string; password: string }
+  >(CoreFilters.AuthenticateUser)
+
 export const [
   doGetInstanceByRequestInfoFilter,
   onGetInstanceByRequestInfoFilter,
@@ -92,6 +134,22 @@ export const [doGetInstanceByIdFilter, onGetInstanceByIdFilter] =
     { instanceId: InstanceId }
   >(CoreFilters.GetInstanceById)
 
+export const [
+  doGetOneInstanceByExactCriteriaFilter,
+  onGetOneInstanceByExactCriteriaFilter,
+] = createCustomFilterWithContext<
+  InstanceFields | undefined,
+  Partial<InstanceFields & { [_: string]: string | number }>
+>(CoreFilters.GetOneInstanceByExactCriteria)
+
+export const [
+  doGetAllInstancesByExactCriteriaFilter,
+  onGetAllInstancesByExactCriteriaFilter,
+] = createCustomFilterWithContext<
+  InstanceFields[],
+  Partial<InstanceFields & { [_: string]: string | number }>
+>(CoreFilters.GetAllInstancesByExactCriteria)
+
 export const [doCliCommandsFilter, onCliCommandsFilter] = createCustomFilter<
   Command[]
 >(CoreFilters.CliCommands)
@@ -106,12 +164,8 @@ export const [
   doGetOrProvisionInstanceUrlFilter,
   onGetOrProvisionInstanceUrlFilter,
 ] = createCustomFilterWithContext<
-  string,
+  string | undefined,
   {
-    req: Request
-    res: Response
-    host: string
-    subdomain: string
     instance: InstanceFields
   }
 >(CoreFilters.GetOrProvisionInstanceUrl)
@@ -136,3 +190,8 @@ export type InstanceConfig = {
 }
 export const [doInstanceConfigFilter, onInstanceConfigFilter] =
   createCustomFilter<InstanceConfig>(CoreFilters.InstanceConfig)
+
+export const [doIsInstanceRunningFilter, onIsInstanceRunningFilter] =
+  createCustomFilterWithContext<boolean, { instance: InstanceFields }>(
+    CoreFilters.IsInstanceRunning,
+  )

package/src/common/schema/BaseFields.ts

@@ -0,0 +1,10 @@
+export type RecordId = string
+export type UserId = RecordId
+export type IsoDate = string
+export type BaseFields = {
+  id: RecordId
+  created: IsoDate
+  updated: IsoDate
+}
+
+export type AnyField = { [_: string]: string | number }

package/src/common/schema/Instance.ts

@@ -1,4 +1,6 @@
 import { doNewInstanceRecordFilter } from '../plugin'
+import { IsoDate } from './BaseFields'
+import { newId, pocketNow } from './util'
 
 export type VersionId = string
 
@@ -21,16 +23,24 @@ export type InstanceSecretCollection = {
 }
 
 export type InstanceFields = {
+  id: string
   subdomain: string
   version: VersionId
   secrets: InstanceSecretCollection
   dev: boolean // Should instance run in --dev mode
+  created: IsoDate
+  updated: IsoDate
 }
 
-export const mkInstance = (subdomain: string) =>
-  doNewInstanceRecordFilter({
+export const mkInstance = (subdomain: string, id = newId()) => {
+  const now = pocketNow()
+  return doNewInstanceRecordFilter({
+    id,
     subdomain,
     version: '*',
     secrets: {},
     dev: false,
+    created: now,
+    updated: now,
   })
+}

package/src/common/schema/util.ts

@@ -1 +1,7 @@
-export const pocketNow = () => new Date().toISOString()
+import { customAlphabet } from 'nanoid'
+import { IsoDate } from './BaseFields'
+
+export const newId = customAlphabet('1234567890abcdefghijklmnopqrstuvwxyz', 10)
+export const pocketNow = () => toPocketDate(new Date())
+export const toPocketDate = (date: Date) => date.toISOString()
+export const fromPocketDate = (iso: IsoDate) => new Date(iso)

package/src/constants.ts

@@ -4,10 +4,9 @@ import { dirname, join } from 'path'
 import { cwd } from 'process'
 import { fileURLToPath } from 'url'
 import { mkBoolean, mkCsvString, mkNumber, mkPath, mkString } from '../core'
-import { InstanceId } from './common'
+import { InstanceFields, InstanceId } from './common'
 import { DEBUG, IS_DEV } from './common/debug'
 import { Settings } from './core/Settings'
-import { logSettings } from './core/logSettings'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 
@@ -17,11 +16,7 @@ config({ path: [join(_PH_HOME, '.env'), join(cwd(), `.env`)] })
 
 export const _PH_PROJECT_DIR = join(__dirname, '..')
 export const _APEX_DOMAIN = process.env.APEX_DOMAIN || 'pockethost.lvh.me'
-export const _HTTP_PROTOCOL = process.env.HTTP_PROTOCOL || `https:`
 
-export function isSettingKey(key: string): key is keyof typeof settings {
-  return key in settings
-}
 export const settings = Settings({
   PH_PLUGINS: mkCsvString([
     `@pockethost/plugin-console-logger`,
@@ -32,6 +27,7 @@ export const settings = Settings({
   PH_HOME: mkPath(_PH_HOME),
   PH_PROJECT_DIR: mkPath(_PH_PROJECT_DIR),
 
+  PH_INTERNAL_HOST: mkString('localhost'),
   PH_APEX_DOMAIN: mkString(_APEX_DOMAIN),
 
   PH_PORT: mkNumber(3000),
@@ -39,6 +35,7 @@ export const settings = Settings({
   PH_DATA_DIR: mkPath(join(_PH_HOME, 'data'), { create: true }),
   PH_DEV: mkBoolean(IS_DEV()),
   PH_DEBUG: mkBoolean(DEBUG()),
+  PH_INTERNAL_APP_SECRET: mkString(''),
 })
 
 /** Accessors */
@@ -57,7 +54,17 @@ export const DATA_DIR = (...paths: string[]) =>
 export const NODE_ENV = () => process.env.NODE_ENV
 export const INSTANCE_DATA_DIR = (id: InstanceId, ...paths: string[]) =>
   join(DATA_DIR(), id, ...paths)
-
-if (DEBUG()) {
-  logSettings(settings)
+export const INTERNAL_HOST = () => settings.PH_INTERNAL_HOST
+export const INTERNAL_APP_SECRET = () => settings.PH_INTERNAL_APP_SECRET
+export const INTERNAL_APP_URL = (...paths: string[]) =>
+  `${HTTP_PROTOCOL()}//${INTERNAL_HOST()}:${PORT()}/${INTERNAL_APP_PREFIX}/${join(
+    ...paths,
+  )}`
+export const INTERNAL_APP_PREFIX = `_internal`
+export const INTERNAL_APP_AUTH_HEADER = `x-pockethost-authorization`
+export const HTTP_PROTOCOL = () => (PORT() === 443 ? 'https:' : 'http:')
+export const PUBLIC_INSTANCE_URL = ({ subdomain }: Partial<InstanceFields>) => {
+  const url = new URL(`${HTTP_PROTOCOL()}//${subdomain}.${APEX_DOMAIN()}`)
+  url.port = `${PORT() === 80 || PORT() == 443 ? '' : PORT()}`
+  return url
 }

package/src/core/config.ts

@@ -0,0 +1,108 @@
+import { forEach, keys, omit, uniq } from '@s-libs/micro-dash'
+import { parse } from 'dotenv'
+import { existsSync, readFileSync, writeFileSync } from 'fs'
+import { info } from '../cli'
+import { PH_HOME, settings } from '../constants'
+
+const envFile = () => {
+  const envFile = PH_HOME(`.env`)
+  if (!existsSync(envFile)) {
+    writeFileSync(envFile, '')
+  }
+  return envFile
+}
+
+export const setConfig = (name: string, value: string) => {
+  if (value === '=') throw new Error(`Invalid value ${value}`)
+
+  const values = _parse()
+  values[name] = value
+  writeFileSync(
+    envFile(),
+    Object.entries(values)
+      .map(([k, v]) => `${k}=${v}`)
+      .join('\n'),
+  )
+  process.env[name] = value
+  info(`Set ${name}=${value}`)
+  info(`Written to ${envFile()}`)
+}
+
+export const unsetConfig = (name: string) => {
+  const values = _parse()
+  delete values[name]
+  writeFileSync(
+    envFile(),
+    Object.entries(values)
+      .map(([k, v]) => `${k}=${v}`)
+      .join('\n'),
+  )
+  info(`Unset ${name}`)
+  info(`Written to ${envFile()}`)
+}
+
+export const listConfig = () => {
+  const values = _parse()
+
+  if (keys(values).length > 0) {
+    info()
+    info(`Config values from ${envFile()}:`)
+    forEach(values, (v, k) => {
+      info(`\t${k}=${v}`)
+    })
+    info()
+  } else {
+    info(`No config values found in ${envFile()}`)
+  }
+
+  const defaults = omit(settings, keys(values) as any)
+  if (keys(defaults).length > 0) {
+    info(`Default values:`)
+    forEach(settings, (v, k) => {
+      if (k in values) return
+      info(`\t${k}=${v}`)
+    })
+  } else {
+    info(`No default values because all values are defined in ${envFile()}`)
+  }
+}
+
+export const appendConfig = (name: string, value: string) => {
+  const values = _parse()
+  values[name] = uniq([
+    ...(values[name]
+      ?.split(/,/)
+      .map((v) => v.trim())
+      .filter((v) => !!v) || []),
+    value,
+  ]).join(`,`)
+  writeFileSync(
+    envFile(),
+    Object.entries(values)
+      .map(([k, v]) => `${k}=${v}`)
+      .join('\n'),
+  )
+  info(`Added ${value} to ${name}`)
+  info(`Written to ${envFile()}`)
+}
+
+export const filterConfig = (name: string, value: string) => {
+  const values = _parse()
+  values[name] = uniq([
+    ...(values[name]
+      ?.split(/,/)
+      .map((v) => v.trim())
+      .filter((v) => v !== value) || []),
+  ]).join(`,`)
+  writeFileSync(
+    envFile(),
+    Object.entries(values)
+      .map(([k, v]) => `${k}=${v}`)
+      .join('\n'),
+  )
+  info(`Filtered ${value} from ${name}`)
+  info(`Written to ${envFile()}`)
+}
+
+export const _parse = () =>
+  parse(readFileSync(envFile(), { encoding: 'utf8' }).toString())

package/src/core/index.ts

@@ -1,8 +1,8 @@
 export * from '../constants'
 export * from './Settings'
 export * from './asyncExecutionGuard'
+export * from './config'
 export * from './exit'
 export * from './internal'
-export * from './logSettings'
 export * from './smartFetch'
 export * from './tryFetch'

package/src/core/tryFetch.ts

@@ -1,4 +1,4 @@
-import fetch, { Response } from 'node-fetch'
+import fetch, { RequestInit, Response } from 'node-fetch'
 import { LoggerService } from '../common'
 
 export const TRYFETCH_RETRY_MS = 50
@@ -6,7 +6,7 @@ export const TRYFETCH_RETRY_MS = 50
 export type TryFetchConfig = {
   preflight: () => Promise<boolean>
   retryMs: number
-}
+} & RequestInit
 
 /**
  * @param url The URL to fetch
@@ -53,7 +53,10 @@ export const tryFetch = async (
       }
       try {
         dbg(`Fetch: START`)
-        const res = await fetch(url, { signal: AbortSignal.timeout(500) })
+        const res = await fetch(url, {
+          ...config,
+          signal: AbortSignal.timeout(500),
+        })
         dbg(`Fetch: SUCCESS`)
         resolve(res)
       } catch (e) {

package/src/plugin.ts

@@ -1,14 +1,19 @@
+import { forEach } from '@s-libs/micro-dash'
 import { produce } from 'immer'
 import {
   PocketHostPlugin,
+  doSettingsFilter,
   namespace,
+  newId,
+  onAfterPluginsLoadedAction,
   onInstanceConfigFilter,
   onInstanceLogAction,
   onServeAction,
   onServeSlugsFilter,
 } from '../common'
-import { dbg } from './cli'
-import { PH_PROJECT_DIR } from './constants'
+import { dbg, info } from './cli'
+import { INTERNAL_APP_SECRET, PH_PROJECT_DIR, settings } from './constants'
+import { setConfig } from './core/config'
 import { serve } from './server'
 
 export const pockethost: PocketHostPlugin = async ({}) => {
@@ -33,4 +38,17 @@ export const pockethost: PocketHostPlugin = async ({}) => {
   onServeSlugsFilter(async (slugs) => {
     return [...slugs, `pockethost`]
   })
+
+  onAfterPluginsLoadedAction(async () => {
+    const allSettings = await doSettingsFilter(settings)
+    forEach(allSettings, (v, k) => {
+      dbg(`${k}: ${v}`)
+    })
+  }, 99)
+
+  onAfterPluginsLoadedAction(async () => {
+    if (INTERNAL_APP_SECRET()) return
+    info(`Generating internal app secret...`)
+    setConfig(`PH_INTERNAL_APP_SECRET`, newId(30))
+  })
 }

package/src/server.ts

@@ -12,7 +12,14 @@ import {
   doRequestErrorAction,
   doRequestErrorMessageFilter,
 } from '../common'
-import { APEX_DOMAIN, PORT, asyncExitHook } from '../core'
+import {
+  APEX_DOMAIN,
+  INTERNAL_APP_AUTH_HEADER,
+  INTERNAL_APP_PREFIX,
+  INTERNAL_APP_SECRET,
+  PORT,
+  asyncExitHook,
+} from '../core'
 
 export const serve = async () => {
   const _proxyLogger = LoggerService().create('ProxyService')
@@ -45,7 +52,25 @@ export const serve = async () => {
   }
   app.use(errorHandler)
 
-  doAppMountedAction({ app })
+  const internalApp = express()
+  internalApp.use((req, res, next) => {
+    dbg(`Got a request to internal app ${req.url}`)
+    next()
+  })
+  internalApp.use((req, res, next) => {
+    const authHeader = req.headers[INTERNAL_APP_AUTH_HEADER]
+    const internalAppSecret = INTERNAL_APP_SECRET()
+
+    if (authHeader !== internalAppSecret) {
+      res.status(403).send('Forbidden')
+      return
+    }
+
+    next()
+  })
+  app.use(`/${INTERNAL_APP_PREFIX}`, internalApp)
+
+  doAppMountedAction({ app, internalApp })
 
   app.all(`*`, async (req, res, next) => {
     const method = req.method
@@ -83,11 +108,7 @@ export const serve = async () => {
     })
 
     const url = await doGetOrProvisionInstanceUrlFilter('', {
-      req,
-      res,
       instance,
-      host,
-      subdomain,
     })
 
     dbg(`Forwarding request for ${req.url} to instance ${url}`)

package/src/core/logSettings.ts

@@ -1,7 +0,0 @@
-import { forEach } from '@s-libs/micro-dash'
-
-export const logSettings = (settings: { [_: string]: any }) => {
-  forEach(settings, (v, k) => {
-    console.log(`${k}: ${v}`)
-  })
-}