feat(config): Add optional Docker extraHosts (part 1)

packages/config/src/satellite/configs/emulator.config.ts

@@ -110,13 +110,18 @@ export interface EmulatorSatellite {
 /**
  * @see EmulatorRunner
  */
+const HostnameSchema = z.string().min(1);
+
 const EmulatorRunnerSchema = z.strictObject({
   type: z.enum(['docker', 'podman']),
   image: z.string().optional(),
   name: z.string().optional(),
   volume: z.string().optional(),
   target: z.string().optional(),
-  platform: z.enum(['linux/amd64', 'linux/arm64']).optional()
+  platform: z.enum(['linux/amd64', 'linux/arm64']).optional(),
+  extraHosts: z
+    .array(z.tuple([HostnameSchema, z.union([z.ipv4(), z.ipv6(), z.literal('host-gateway'), HostnameSchema])]))
+    .optional()
 });
 
 /**
@@ -155,6 +160,26 @@ export interface EmulatorRunner {
    * The platform to use when running the emulator container.
    */
   platform?: 'linux/amd64' | 'linux/arm64';
+
+  /**
+   * Additional host-to-IP mappings to inject into the container via `--add-host`.
+   * Each entry is a `[hostname, destination]` tuple where destination is an IPv4
+   * address, an IPv6 address, `"host-gateway"`, or an arbitrary host string.
+   *
+   * This is useful for making host-machine services (e.g. a local Ethereum RPC
+   * node) reachable from within the container under a stable DNS name such as
+   * `host.docker.internal`.
+   *
+   * @example
+   * ```ts
+   * runner: {
+   *   extraHosts: [['host.docker.internal', 'host-gateway']]
+   * }
+   * ```
+   *
+   * @see https://docs.docker.com/reference/cli/docker/container/run/#add-host
+   */
+  extraHosts?: [string, string][];
 }
 
 /**

packages/config/src/tests/satellite/configs/emulator.config.spec.ts

@@ -591,5 +591,101 @@ describe('emulator.config', () => {
         expect(res.success).toBe(true);
       });
     });
+
+    describe('runner.extraHosts', () => {
+      const withExtraHosts = (extraHosts: unknown) => ({
+        skylab: {},
+        runner: {type: 'docker', extraHosts}
+      });
+
+      it('accepts a valid IPv4 entry', () => {
+        const result = EmulatorConfigSchema.safeParse(
+          withExtraHosts([['myhost', '192.168.1.1']])
+        );
+        expect(result.success).toBe(true);
+      });
+
+      it('accepts a valid IPv6 entry', () => {
+        const result = EmulatorConfigSchema.safeParse(
+          withExtraHosts([['myhost', '::1']])
+        );
+        expect(result.success).toBe(true);
+      });
+
+      it('accepts "host-gateway" as a destination', () => {
+        const result = EmulatorConfigSchema.safeParse(
+          withExtraHosts([['host.docker.internal', 'host-gateway']])
+        );
+        expect(result.success).toBe(true);
+      });
+
+      it('accepts an arbitrary non-empty string as a destination (fallback hostname)', () => {
+        const result = EmulatorConfigSchema.safeParse(
+          withExtraHosts([['myhost', 'some-other-host']])
+        );
+        expect(result.success).toBe(true);
+      });
+
+      it('accepts multiple entries', () => {
+        const result = EmulatorConfigSchema.safeParse(
+          withExtraHosts([
+            ['host.docker.internal', 'host-gateway'],
+            ['eth-rpc', '192.168.0.10'],
+            ['ipv6host', '2001:db8::1']
+          ])
+        );
+        expect(result.success).toBe(true);
+      });
+
+      it('accepts an empty array', () => {
+        const result = EmulatorConfigSchema.safeParse(withExtraHosts([]));
+        expect(result.success).toBe(true);
+      });
+
+      it('is optional (omitted entirely)', () => {
+        const result = EmulatorConfigSchema.safeParse({skylab: {}, runner: {type: 'docker'}});
+        expect(result.success).toBe(true);
+      });
+
+      it('rejects the old flat-string format', () => {
+        const result = EmulatorConfigSchema.safeParse(
+          withExtraHosts(['host.docker.internal:host-gateway'])
+        );
+        expect(result.success).toBe(false);
+      });
+
+      it('rejects an entry with an empty hostname', () => {
+        const result = EmulatorConfigSchema.safeParse(
+          withExtraHosts([['', '192.168.1.1']])
+        );
+        expect(result.success).toBe(false);
+      });
+
+      it('rejects an entry with an empty destination', () => {
+        const result = EmulatorConfigSchema.safeParse(
+          withExtraHosts([['myhost', '']])
+        );
+        expect(result.success).toBe(false);
+      });
+
+      it('rejects a tuple with more than two elements', () => {
+        const result = EmulatorConfigSchema.safeParse(
+          withExtraHosts([['myhost', '192.168.1.1', 'extra']])
+        );
+        expect(result.success).toBe(false);
+      });
+
+      it('rejects a tuple with only one element', () => {
+        const result = EmulatorConfigSchema.safeParse(
+          withExtraHosts([['myhost']])
+        );
+        expect(result.success).toBe(false);
+      });
+
+      it('rejects a non-array value', () => {
+        const result = EmulatorConfigSchema.safeParse(withExtraHosts('invalid'));
+        expect(result.success).toBe(false);
+      });
+    });
   });
 });