opnsense_diag_log_gateways

Instructions

Implementation Reference

• src/tools/diagnostics.ts:415-419 (handler)

  Handler for opnsense_diag_log_gateways: parses args with LogQuerySchema, calls fetchLogWithFallback with category 'gateways', and returns the result as JSON.

  case "opnsense_diag_log_gateways": {
    const parsed = LogQuerySchema.parse(args);
    const result = await fetchLogWithFallback(client, "gateways", parsed.limit);
    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
  }

• src/tools/diagnostics.ts:33-35 (schema)

  LogQuerySchema used for input validation: optional 'limit' (coerced number, 1-5000, default 500).

  const LogQuerySchema = z.object({
    limit: z.coerce.number().int().min(1).max(5000).optional().default(500),
  });

• src/tools/diagnostics.ts:154-163 (registration)

  Tool definition registration in diagnosticsToolDefinitions array, with name, description, and inputSchema for ListTools response.

  {
    name: "opnsense_diag_log_gateways",
    description: "Retrieve recent OPNsense gateway monitoring (dpinger) log entries — useful for WAN/gateway health debugging.",
    inputSchema: {
      type: "object" as const,
      properties: {
        limit: { type: "number", description: "Number of log entries (1-5000, default 500)" },
      },
    },
  },

• src/tools/diagnostics.ts:207-251 (helper)

  fetchLogWithFallback helper: tries multiple API endpoint variants (GET /diagnostics/log/gateways, POST /diagnostics/log/gateways/search, GET /diagnostics/log/core/gateways) with fallback logic to retrieve gateway log entries.

  async function fetchLogWithFallback(
    client: OPNsenseClient,
    category: string,
    limit: number,
  ): Promise<unknown> {
    type Variant = { method: "get" | "post"; path: string; body?: unknown };
    const variants: Variant[] = [
      { method: "get", path: `/diagnostics/log/${category}?limit=${limit}` },
      {
        method: "post",
        path: `/diagnostics/log/${category}/search`,
        body: { current: 1, rowCount: limit, sort: {}, searchPhrase: "" },
      },
      { method: "get", path: `/diagnostics/log/core/${category}?limit=${limit}` },
    ];
  
    let lastResult: unknown = null;
    let lastError: unknown = null;
  
    for (const variant of variants) {
      try {
        const result =
          variant.method === "get"
            ? await client.get<unknown>(variant.path)
            : await client.post<unknown>(variant.path, variant.body);
  
        // A non-empty payload wins. Treat the result as non-empty if:
        //   - array with length > 0
        //   - object with rows[].length > 0
        //   - object with any other non-empty data field
        if (isNonEmptyLogPayload(result)) {
          return result;
        }
        lastResult = result;
      } catch (error) {
        lastError = error;
        // Endpoint not present (404) → keep trying. Other errors propagate
        // only if every variant fails.
      }
    }
  
    if (lastResult !== null) return lastResult;
    if (lastError) throw lastError;
    return [];
  }

• src/index.ts:61-61 (registration)

  Registers handleDiagnosticsTool as the handler for all diagnostics tools (including opnsense_diag_log_gateways) in the toolHandlers map.

  for (const def of diagnosticsToolDefinitions) toolHandlers.set(def.name, handleDiagnosticsTool);