Merge pull request #529 from sij411/feat/tunnel-service

Add --tunnel-service option to lookup, inbox, and relay commands

Author: dahlia

docs/cli.md

@@ -787,6 +787,19 @@ the [ActivityPub HTTP Signatures] specification.
 [RFC 9421]: https://www.rfc-editor.org/rfc/rfc9421
 [ActivityPub HTTP Signatures]: https://swicg.github.io/activitypub-http-signature/
 
+### `--tunnel-service`: Tunneling service for `-a`/`--authorized-fetch`
+
+The `--tunnel-service` option is used to specify which tunneling service to use
+when using the `-a`/`--authorized-fetch` option.  The authorized fetch feature
+requires a temporary server to be exposed to the public internet, and this
+option allows you to choose the tunneling service.  Available services can be
+found in the output of the `fedify lookup --help` command.  For example, to use
+serveo.net as the tunneling service:
+
+~~~~ sh
+fedify lookup --authorized-fetch --tunnel-service serveo.net @user@example.com
+~~~~
+
 ### `-u`/`--user-agent`: Custom `User-Agent` header
 
 *This option is available since Fedify 1.3.0.*
@@ -966,6 +979,20 @@ about the security implications of exposing the server to the public internet.
 > If you disable the tunneling feature, the ephemeral ActivityPub instance will
 > be served via HTTP instead of HTTPS.
 
+### `--tunnel-service`: Tunneling service
+
+The `--tunnel-service` option is used to specify which tunneling service to use
+for exposing the ephemeral inbox server to the public internet.  Available
+services can be found in the output of the `fedify inbox --help` command.
+For example, to use serveo.net as the tunneling service:
+
+~~~~ sh
+fedify inbox --tunnel-service serveo.net
+~~~~
+
+> [!NOTE]
+> This option cannot be used together with `-T`/`--no-tunnel`.
+
 ### `-A`/`--authorized-fetch`: Authorized fetch mode
 
 The `-A`/`--authorized-fetch` option enables authorized fetch mode on the
@@ -1126,11 +1153,13 @@ fedify tunnel 3000
 
 [x-forwarded-fetch]: https://github.com/dahlia/x-forwarded-fetch
 
-### `-s`/`--service`: The tunneling service
+### `-s`/`--service`/`--tunnel-service`: The tunneling service
 
 The `-s`/`--service` option is used to specify the tunneling service to use.
-Available services can be found in the output of the `fedify tunnel --help`
-command.  For example, to use the serveo.net, run the below command:
+The `--tunnel-service` is an alias for consistency with other commands that
+support tunneling.  Available services can be found in the output of the
+`fedify tunnel --help` command.  For example, to use serveo.net, run the below
+command:
 
 ~~~~ sh
 fedify tunnel --service serveo.net 3000

packages/cli/src/inbox.tsx

@@ -44,6 +44,7 @@ import ora from "ora";
 import metadata from "../deno.json" with { type: "json" };
 import { getDocumentLoader } from "./docloader.ts";
 import { configureLogging, debugOption } from "./globals.ts";
+import { tunnelOption } from "./options.ts";
 import type { ActivityEntry } from "./inbox/entry.ts";
 import { ActivityEntryPage, ActivityListPage } from "./inbox/view.tsx";
 import { recordingSink } from "./log.ts";
@@ -86,14 +87,9 @@ export const inboxCommand = command(
           }),
         ),
       ),
-      noTunnel: option(
-        "-T",
-        "--no-tunnel",
-        {
-          description:
-            message`Do not tunnel the ephemeral ActivityPub server to the public Internet.`,
-        },
-      ),
+    }),
+    tunnelOption,
+    object({
       actorName: withDefault(
         option("--actor-name", string({ metavar: "NAME" }), {
           description: message`Customize the actor display name.`,
@@ -334,7 +330,8 @@ export async function runInbox(
     discardStdin: false,
   }).start();
   const server = await spawnTemporaryServer(fetch, {
-    noTunnel: command.noTunnel,
+    noTunnel: !command.tunnel,
+    ...(command.tunnel && { service: command.tunnelService }),
   });
   spinner.succeed(
     `The ephemeral ActivityPub server is up and running: ${

packages/cli/src/lookup.ts

@@ -42,16 +42,20 @@ import ora from "ora";
 import { getContextLoader, getDocumentLoader } from "./docloader.ts";
 import { configureLogging, debugOption } from "./globals.ts";
 import { renderImages } from "./imagerenderer.ts";
+import { tunnelServiceOption } from "./options.ts";
 import { spawnTemporaryServer, type TemporaryServer } from "./tempserver.ts";
 import { colorEnabled, colors, formatObject } from "./utils.ts";
 
 const logger = getLogger(["fedify", "cli", "lookup"]);
 
-export const authorizedFetchOption = withDefault(
+export const authorizedFetchOption = or(
   object({
-    authorizedFetch: flag("-a", "--authorized-fetch", {
-      description: message`Sign the request with an one-time key.`,
-    }),
+    authorizedFetch: map(
+      flag("-a", "--authorized-fetch", {
+        description: message`Sign the request with an one-time key.`,
+      }),
+      () => true as const,
+    ),
     firstKnock: withDefault(
       option(
         "--first-knock",
@@ -64,8 +68,11 @@ export const authorizedFetchOption = withDefault(
       ),
       "draft-cavage-http-signatures-12" as const,
     ),
+    tunnelService: tunnelServiceOption,
+  }),
+  object({
+    authorizedFetch: constant(false as const),
   }),
-  { authorizedFetch: false } as const,
 );
 
 const traverseOption = withDefault(
@@ -358,7 +365,7 @@ export async function runLookup(command: InferValue<typeof lookupCommand>) {
         }),
         { contextLoader },
       );
-    });
+    }, { service: command.tunnelService });
     const baseAuthLoader = getAuthenticatedDocumentLoader(
       {
         keyId: new URL("#main-key", server.url),

packages/cli/src/options.ts

@@ -0,0 +1,65 @@
+import {
+  choice,
+  constant,
+  flag,
+  map,
+  message,
+  object,
+  option,
+  optional,
+  or,
+  valueSet,
+} from "@optique/core";
+
+/**
+ * Available tunneling services for exposing local servers to the public internet.
+ */
+export const TUNNEL_SERVICES = [
+  "localhost.run",
+  "serveo.net",
+  "pinggy.io",
+] as const;
+
+/**
+ * Type representing a valid tunneling service.
+ */
+export type TunnelService = typeof TUNNEL_SERVICES[number];
+
+/**
+ * Option for selecting a tunneling service.
+ * Use this when tunneling is implicit (e.g., in `lookup` with `-a`).
+ */
+export const tunnelServiceOption = optional(
+  option(
+    "--tunnel-service",
+    choice(TUNNEL_SERVICES, { metavar: "SERVICE" }),
+    {
+      description: message`The tunneling service to use: ${
+        valueSet(TUNNEL_SERVICES)
+      }.`,
+    },
+  ),
+);
+
+/**
+ * Combined option for enabling/disabling tunneling with service selection.
+ * Use this when tunneling can be disabled (e.g., in `inbox` and `relay`).
+ *
+ * Returns either:
+ * - `{ tunnel: false }` when `--no-tunnel` is specified
+ * - `{ tunnel: true, tunnelService?: TunnelService }` otherwise
+ */
+export const tunnelOption = or(
+  object({
+    tunnel: map(
+      flag("-T", "--no-tunnel", {
+        description: message`Do not tunnel the server to the public Internet.`,
+      }),
+      () => false as const,
+    ),
+  }),
+  object({
+    tunnel: constant(true),
+    tunnelService: tunnelServiceOption,
+  }),
+);

packages/cli/src/relay.ts

@@ -24,6 +24,7 @@ import { DatabaseSync } from "node:sqlite";
 import process from "node:process";
 import ora from "ora";
 import { configureLogging, debugOption } from "./globals.ts";
+import { tunnelOption } from "./options.ts";
 import { tableStyle } from "./table.ts";
 import { spawnTemporaryServer, type TemporaryServer } from "./tempserver.ts";
 import { colors, matchesActor } from "./utils.ts";
@@ -82,11 +83,8 @@ export const relayCommand = command(
             message`Reject follow requests from the given actor. The argument can be either an actor URI or a handle, or a wildcard (${"*"}). Can be specified multiple times. If a wildcard is specified, all follow requests will be rejected.`,
         }),
       )),
-      noTunnel: option("-T", "--no-tunnel", {
-        description:
-          message`Disable tunneling the relay server to the public internet. Local access only.`,
-      }),
     }),
+    tunnelOption,
     debugOption,
   ),
   {
@@ -140,7 +138,11 @@ export async function runRelay(
 
   server = await spawnTemporaryServer(async (request) => {
     return await relay.fetch(request);
-  }, { noTunnel: command.noTunnel, port: command.port });
+  }, {
+    noTunnel: !command.tunnel,
+    port: command.port,
+    ...(command.tunnel && { service: command.tunnelService }),
+  });
 
   relay = createRelay(
     command.protocol as RelayType,

packages/cli/src/tempserver.ts

@@ -1,12 +1,14 @@
 import { openTunnel } from "@hongminhee/localtunnel";
 import { getLogger } from "@logtape/logtape";
 import { serve } from "srvx";
+import type { TunnelService } from "./options.ts";
 
 const logger = getLogger(["fedify", "cli", "tempserver"]);
 
 export type SpawnTemporaryServerOptions = {
   noTunnel?: boolean;
   port?: number;
+  service?: TunnelService;
 };
 
 export type TemporaryServer = {
@@ -80,7 +82,10 @@ export async function spawnTemporaryServer(
   const port = url.port;
 
   logger.debug("Temporary server is listening on port {port}.", { port });
-  const tun = await openTunnel({ port: parseInt(port) });
+  const tun = await openTunnel({
+    port: parseInt(port),
+    service: options.service,
+  });
   logger.debug("Temporary server is tunneled to {url}.", { url: tun.url.href });
 
   return {

packages/cli/src/tunnel.ts

@@ -10,8 +10,10 @@ import {
   object,
   option,
   optional,
+  valueSet,
 } from "@optique/core";
 import { choice } from "@optique/core/valueparser";
+import { TUNNEL_SERVICES } from "./options.ts";
 import { print, printError } from "@optique/run";
 import process from "node:process";
 import ora from "ora";
@@ -32,10 +34,15 @@ export const tunnelCommand = command(
         option(
           "-s",
           "--service",
-          choice(["localhost.run", "serveo.net", "pinggy.io"], {
+          "--tunnel-service",
+          choice(TUNNEL_SERVICES, {
             metavar: "SERVICE",
           }),
-          { description: message`The tunneling service to use.` },
+          {
+            description: message`The tunneling service to use: ${
+              valueSet(TUNNEL_SERVICES)
+            }.`,
+          },
         ),
       ),
     }),