Tiyi v3.8.0

upstream.proto — Upstream pools

Schema: tiyi.v1 · upstream.proto · English guide · 中文指南 · Full RPC index

Services

UpstreamService

RPC Kind Required permission
ListUpstreams unary (upstream:read)
GetUpstream unary (upstream:read)
CreateUpstream unary (upstream:write)
UpdateUpstream unary (upstream:write)
DeleteUpstream unary (upstream:delete)
ListUpstreamHealth unary (upstream:read)

RPCs

UpstreamService.ListUpstreams

Request — tiyi.v1.ListUpstreamsRequest

Field JSON key Type Cardinality Description
page page PageRequest singular —
query query string singular —

Response — tiyi.v1.ListUpstreamsResponse

Field JSON key Type Cardinality Description
items items Upstream repeated —
page page PageResponse singular —

UpstreamService.GetUpstream

Request — tiyi.v1.GetUpstreamRequest

Field JSON key Type Cardinality Description
id id string singular —

Response — tiyi.v1.GetUpstreamResponse

Field JSON key Type Cardinality Description
upstream upstream Upstream singular —

UpstreamService.CreateUpstream

Request — tiyi.v1.CreateUpstreamRequest

Field JSON key Type Cardinality Description
upstream upstream Upstream singular —

Response — tiyi.v1.CreateUpstreamResponse

Field JSON key Type Cardinality Description
upstream upstream Upstream singular —

UpstreamService.UpdateUpstream

Request — tiyi.v1.UpdateUpstreamRequest

Field JSON key Type Cardinality Description
upstream upstream Upstream singular —
update_mask updateMask google.protobuf.FieldMask singular comma-joined field paths, e.g. "name,status".

Response — tiyi.v1.UpdateUpstreamResponse

Field JSON key Type Cardinality Description
upstream upstream Upstream singular —

UpstreamService.DeleteUpstream

Request — tiyi.v1.DeleteUpstreamRequest

Field JSON key Type Cardinality Description
id id string singular —

Response — tiyi.v1.DeleteUpstreamResponse

Field JSON key Type Cardinality Description
result result MutationResult singular —

UpstreamService.ListUpstreamHealth

Request — tiyi.v1.ListUpstreamHealthRequest

Field JSON key Type Cardinality Description
upstream_ids upstreamIds string repeated Up to 200 pools. Omit to query all pools.

Response — tiyi.v1.ListUpstreamHealthResponse

Field JSON key Type Cardinality Description
items items UpstreamHealthState repeated —
expected_node_ids expectedNodeIds string repeated The built-in node and every enrolled, non-deleted remote node, including offline nodes and nodes which have never reported health.

Messages

Upstream

Field JSON key Type Cardinality Description
id id string singular —
tenant_id tenantId string singular —
name name string singular —
description description string singular —
endpoints endpoints UpstreamEndpoint repeated —
status status ResourceStatus singular —
created_at createdAt google.protobuf.Timestamp singular RFC 3339 string, e.g. 2026-07-26T09:00:00Z.
updated_at updatedAt google.protobuf.Timestamp singular RFC 3339 string, e.g. 2026-07-26T09:00:00Z.
deleted_at deletedAt google.protobuf.Timestamp singular RFC 3339 string, e.g. 2026-07-26T09:00:00Z.
health_check healthCheck UpstreamHealthCheck singular —
resilience resilience UpstreamResiliencePolicy singular —
request_headers requestHeaders map<string, string> map Plaintext request headers applied to every request sent through this pool. These are ordinary portable configuration, not secret material.

UpstreamHealthCheck

UpstreamHealthCheck is the pool-level active probe contract compiled into Caddy. An empty path disables active checks. Defaults are applied server-side when optional tuning values are omitted.

Field JSON key Type Cardinality Description
path path string singular —
method method string singular —
expected_status expectedStatus int32 singular —
interval_seconds intervalSeconds int32 singular —
timeout_seconds timeoutSeconds int32 singular —
unhealthy_threshold unhealthyThreshold int32 singular —
healthy_threshold healthyThreshold int32 singular —
follow_redirects followRedirects bool singular —
expected_body expectedBody string singular —
host host string singular —

UpstreamHealthState

Field JSON key Type Cardinality Description
node_id nodeId string singular —
upstream_id upstreamId string singular —
endpoint_url endpointUrl string singular —
address address string singular —
status status string singular unknown | healthy | unhealthy
reported_at reportedAt google.protobuf.Timestamp singular RFC 3339 string, e.g. 2026-07-26T09:00:00Z.
last_transition_at lastTransitionAt google.protobuf.Timestamp singular RFC 3339 string, e.g. 2026-07-26T09:00:00Z.
config_generation configGeneration int64 singular JSON string (64-bit ints are quoted).
artifact_sha256 artifactSha256 string singular —

UpstreamResiliencePolicy

UpstreamResiliencePolicy protects real traffic independently of active probes. When this message is omitted, the server enables passive failure ejection (30 seconds / 2 failures) and safe bounded retries (5 seconds / 250 milliseconds). Explicit booleans allow either lane to be disabled without changing the active health-check contract.

Field JSON key Type Cardinality Description
passive_health_enabled passiveHealthEnabled bool singular —
passive_fail_duration_seconds passiveFailDurationSeconds int32 singular —
passive_max_fails passiveMaxFails int32 singular —
retry_enabled retryEnabled bool singular —
retry_duration_seconds retryDurationSeconds int32 singular —
retry_interval_milliseconds retryIntervalMilliseconds int32 singular —
← PreviousAPI integration