GoodMemGoodMem
ReferenceSdkV2Go

Ping

package goodmem // import "fury.io/pairsys/goodmem"

Endpoint health probes — single-shot and streaming.

Methods are called as client.Ping().<Method>(ctx, ...) on a *goodmem.Client. Service: PingService.

Index

type PingService

type PingService struct{ … }

Access this service as client.Ping() on a *goodmem.Client. Its methods follow.

func (s *PingService) Once

func (s *PingService) Once(ctx context.Context, req *models.PingOnceRequest) (*models.PingResult, error)

Runs a single ping probe and returns the probe result.

HTTP — POST /v1/ping:once

Parameters

  • ctx (context.Context) — carries the deadline and cancellation signal for the call.
  • req (*models.PingOnceRequest) — the request payload. The linked type documents every field and its JSON wire name.

Returns — (*models.PingResult, error)

Example

result, err := client.Ping().Once(ctx, &models.PingOnceRequest{TargetID: "your-embedder-id"})
if err != nil {
	log.Fatal(err)
}
_ = result.RttMs
_ = result.Ok

func (s *PingService) Stream

func (s *PingService) Stream(ctx context.Context, req *models.PingStreamRequest) (*Stream[models.PingEvent], error)

Opens a streaming ping session and returns per-probe results plus a terminal summary.

HTTP — POST /v1/ping:stream

Parameters

  • ctx (context.Context) — carries the deadline and cancellation signal for the call.
  • req (*models.PingStreamRequest) — the request payload. The linked type documents every field and its JSON wire name.

Returns — (*Stream[models.PingEvent], error)

Example

stream, err := client.Ping().Stream(ctx, &models.PingStreamRequest{TargetID: "your-embedder-id", Count: goodmem.Ptr(int32(2))})
if err != nil {
	log.Fatal(err)
}
defer stream.Close()
for event, err := range stream.Events() {
	if err != nil {
		log.Fatal(err)
	}
	_ = event
}

type PingOnceRequest

type PingOnceRequest struct{ … }

Request payload for a single ping probe

  • TargetID (string, wire targetId) — Target resource ID (UUID)
  • TargetTypeHint (models.PingTargetType, optional, wire targetTypeHint) — Optional hint for the target resource type
  • PayloadType (models.PingPayloadType, optional, wire payloadType) — Desired payload type (defaults to provider-specific value)
  • Payload (string, optional, wire payload) — Explicit UTF-8 payload to send with the probe (mutually exclusive with payloadSizeBytes)
  • PayloadSizeBytes (int32, optional, wire payloadSizeBytes) — Synthetic payload size in bytes (mutually exclusive with payload)
  • TimeoutMs (int32, optional, wire timeoutMs) — Per-probe timeout in milliseconds (0 uses server default)

type PingTargetType

type PingTargetType string

Target types for ping operations

String enum (type PingTargetType string): "TARGET_TYPE_UNSPECIFIED" · "EMBEDDER" · "RERANKER" · "LLM"

type PingPayloadType

type PingPayloadType string

Payload types supported by ping operations

String enum (type PingPayloadType string): "PAYLOAD_TYPE_UNSPECIFIED" · "TEXT" · "JSON" · "BINARY"

type PingResult

type PingResult struct{ … }

Result from an individual ping probe

  • Endpoint (models.PingEndpointInfo, wire endpoint) — Resolved endpoint metadata for the target
  • Seq (int32, wire seq) — Sequential probe number (1-based)
  • BytesSent (int32, wire bytesSent) — Payload bytes transmitted
  • BytesReceived (int32, wire bytesReceived) — Payload bytes received
  • Ok (bool, wire ok) — True when the provider responded successfully within the timeout
  • HTTPStatus (int32, wire httpStatus) — Provider HTTP status code or equivalent transport status
  • ErrorMessage (string, optional, wire errorMessage) — Human-readable error message when ok=false
  • RttMs (float64, wire rttMs) — Observed round-trip latency in milliseconds
  • Timing (models.PingTiming, wire timing) — Raw timing data recorded on the server
  • Metadata (map[string]string, optional, wire metadata) — Additional provider metadata (request IDs, throttling signals, etc.)

type PingEndpointInfo

type PingEndpointInfo struct{ … }

Resolved endpoint metadata for ping responses

  • TargetType (models.PingTargetType, wire targetType) — Resolved resource type
  • TargetID (string, wire targetId) — Target resource ID (UUID)
  • ResolvedEndpoint (string, wire resolvedEndpoint) — Fully resolved endpoint URL used for the probe
  • Provider (string, wire provider) — Provider name backing the resource
  • ModelIdentifier (string, wire modelIdentifier) — Provider-specific model identifier

type PingTiming

type PingTiming struct{ … }

Timing information captured during a ping probe

  • ClientSendTimeUnixNanos (int64, wire clientSendTimeUnixNanos) — Client send time (Unix epoch nanoseconds)
  • ServerReceivedTimeUnixNanos (int64, wire serverReceivedTimeUnixNanos) — Server received time (Unix epoch nanoseconds)
  • ServerSendTimeUnixNanos (int64, wire serverSendTimeUnixNanos) — Server send time (Unix epoch nanoseconds)
  • ClientReceiveTimeUnixNanos (int64, wire clientReceiveTimeUnixNanos) — Client receive time (Unix epoch nanoseconds)

type PingStreamRequest

type PingStreamRequest struct{ … }

Request payload for a streaming ping session

  • TargetID (string, wire targetId) — Target resource ID (UUID)
  • TargetTypeHint (models.PingTargetType, optional, wire targetTypeHint) — Optional hint for the target resource type
  • Count (int32, optional, wire count) — Number of probes to run (0 uses server default)
  • IntervalMs (int32, optional, wire intervalMs) — Delay between probes in milliseconds (0 uses server default)
  • TimeoutMs (int32, optional, wire timeoutMs) — Per-probe timeout in milliseconds (0 uses server default)
  • PayloadType (models.PingPayloadType, optional, wire payloadType) — Desired payload type (defaults to provider-specific value)
  • Payload (string, optional, wire payload) — Explicit UTF-8 payload to send with each probe (mutually exclusive with payloadSizeBytes)
  • PayloadSizeBytes (int32, optional, wire payloadSizeBytes) — Synthetic payload size in bytes (mutually exclusive with payload)
  • MaxInFlight (int32, optional, wire maxInFlight) — Maximum concurrent probes (defaults to 1)
  • Jitter (bool, optional, wire jitter) — Add jitter to probe scheduling
  • Labels (map[string]string, optional, wire labels) — Optional labels to attach to the ping session

type PingEvent

type PingEvent struct{ … }

Streaming event from a ping session

  • Result (models.PingResult, optional, wire result) — Probe result event
  • Summary (models.PingSummary, optional, wire summary) — Summary emitted at session completion
  • Notice (models.PingNotice, optional, wire notice) — Non-fatal notice emitted during session

type PingSummary

type PingSummary struct{ … }

Summary emitted at the end of a ping session

  • Endpoint (models.PingEndpointInfo, wire endpoint) — Endpoint metadata copied from the final probe
  • Requests (int32, wire requests) — Total number of probes scheduled
  • Responses (int32, wire responses) — Number of responses received (including timeouts/errors)
  • Ok (int32, wire ok) — Count of probes that succeeded
  • Timeouts (int32, wire timeouts) — Count of probes that exceeded the timeout
  • Errors (int32, wire errors) — Count of probes that failed for other reasons
  • RttMinMs (float64, wire rttMinMs) — Minimum observed round-trip latency (ms)
  • RttAvgMs (float64, wire rttAvgMs) — Average observed round-trip latency (ms)
  • RttP50Ms (float64, wire rttP50Ms) — Median (p50) round-trip latency (ms)
  • RttP90Ms (float64, wire rttP90Ms) — 90th percentile round-trip latency (ms)
  • RttP99Ms (float64, wire rttP99Ms) — 99th percentile round-trip latency (ms)
  • RttMaxMs (float64, wire rttMaxMs) — Maximum observed round-trip latency (ms)
  • RequestsPerSecond (float64, wire requestsPerSecond) — Effective request throughput across the session
  • BytesPerSecond (float64, wire bytesPerSecond) — Aggregate bytes per second (send + receive)
  • AppliedLimits (map[string]string, optional, wire appliedLimits) — Resource limits applied by the server

type PingNotice

type PingNotice struct{ … }

Non-fatal notice emitted during a ping session

  • Code (string, wire code) — Machine-readable notice identifier
  • Message (string, wire message) — Human-readable notice message
  • Details (map[string]string, optional, wire details) — Additional contextual details

On this page

Indextype PingServicefunc (s *PingService) Oncefunc (s *PingService) Streamtype PingOnceRequesttype PingTargetTypetype PingPayloadTypetype PingResulttype PingEndpointInfotype PingTimingtype PingStreamRequesttype PingEventtype PingSummarytype PingNotice