Module: Woods::MCP::ProviderProbe

Defined in:
lib/woods/mcp/provider_probe.rb

Overview

Probes an embedding provider’s HTTP endpoint to confirm it is reachable before the MCP server commits to a fully-hydrated start.

A probe is pure: input → result-or-raise. No logging, no stderr writes, no side effects. The caller decides what to do with a failure.

Raises ProviderUnreachable on any network failure with structured url: and reason: fields so callers can pattern-match on the reason string. Raises ArgumentError for unknown provider classes —that is a programming error, not a runtime condition.

Examples:

Woods::MCP::ProviderProbe.reachable!(provider)  # → provider or raises

Constant Summary collapse

OLLAMA_OPEN_TIMEOUT =

Connect timeout for Ollama probes (LAN/localhost — fail fast).

0.5
OLLAMA_READ_TIMEOUT =

Read timeout for Ollama probes.

0.5
OPENAI_OPEN_TIMEOUT =

Connect timeout for OpenAI probes (WAN — allow for latency).

2.0
OPENAI_READ_TIMEOUT =

Read timeout for OpenAI probes.

2.0

Class Method Summary collapse

Class Method Details

.reachable!(provider) ⇒ Object

Probe provider and return it if reachable.

Dispatches on the provider’s concrete class:

  • Embedding::Provider::Ollama → GET /api/tags on the configured host. Any non-5xx response is treated as reachable.

  • Embedding::Provider::OpenAI → GET /v1/models on api.openai.com:443. A 401 response raises ProviderUnreachable with reason: “unauthorized” because an invalid key means the provider cannot be used; network failures raise with the appropriate reason string.

  • Any other class → raises ArgumentError.

Parameters:

Returns:

  • (Object) —

    the same provider if reachable

Raises:

  • (Woods::MCP::ProviderUnreachable) —

    if the endpoint is unreachable, times out, returns 5xx, or (for OpenAI) returns 401

  • (ArgumentError) —

    if provider is not a recognised provider class



50
51
52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/woods/mcp/provider_probe.rb', line 50

def self.reachable!(provider)
  case provider
  when Woods::Embedding::Provider::Ollama
    probe_ollama!(provider)
  when Woods::Embedding::Provider::OpenAI
    probe_openai!(provider)
  else
    raise ArgumentError,
          "#{self}.reachable! does not know how to probe #{provider.class} — " \
          'add a provider-specific probe method or implement #probe_url'
  end
  provider
end