Help us shape the future of Go! Take the 2026 Go Developer Survey

ingress

package
v1.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 28, 2026 License: MIT Imports: 6 Imported by: 16

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func WithAuthKey added in v0.25.0 

func WithAuthKey(authKey string) withAuthKey

WithAuthKey sets the authentication key sent with requests by the ingress Client.

func WithHttpClient added in v0.25.0 

func WithHttpClient(c *http.Client) withHttpClient

WithHttpClient sets the HTTP client used by the ingress Client.

Types

type Client 

type Client = ingress.Client

func NewClient 

func NewClient(baseUri string, opts ...ClientOption) *Client

NewClient creates a new ingress client for calling Restate services from outside a Restate context. The baseUri should point to your Restate ingress endpoint (e.g., "http://localhost:8080").

Options can be used to configure the client, such as setting a custom HTTP client, authentication key, or codec: 

client := ingress.NewClient("http://localhost:8080",
    restate.WithAuthKey("my-auth-key"),
)

To setup OpenTelemetry tracing, provide an HTTP client wrapped using the otel transport: 

import "go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"

client := ingress.NewClient("http://localhost:8080",
    // HTTP client wrapped with the otel transport.
    restate.WithHttpClient(&http.Client{Transport: otelhttp.NewTransport(http.DefaultTransport)}),
)

type ClientOption added in v0.25.0 

type ClientOption = options.IngressClientOption

ClientOption configures an ingress Client; pass it to NewClient.

type Error added in v1.1.0 

type Error = ingress.Error

Error is implemented by every error the ingress Client returns for a non-2xx response from the Restate ingress. It exposes the Restate error code, the message, an optional stacktrace, and whether the failure came from the invocation (the handler ran and terminally failed) or from the ingress itself.

Match it with errors.As: 

var ie ingress.Error
if errors.As(err, &ie) {
    ie.Code()              // e.g. restate.Code(403)
    ie.IsInvocationError() // true if the handler terminally failed
}

When IsInvocationError reports true, the error also satisfies the SDK terminal-error model, so restate.AsTerminalError(err) and restate.IsTerminalError(err) work on it.

type InvocationHandle 

type InvocationHandle[O any] interface {
	// Attach calls the attach API and blocks until the output is available. On failure it
	// returns an [Error]; use errors.As to check for an [InvocationNotFoundError] when the
	// invocation does not exist.
	Attach(ctx context.Context) (O, error)
	// Output calls the attachment API and returns the output if available. On failure it
	// returns an [Error]: use errors.As to check for an [InvocationNotFoundError] when the
	// invocation does not exist, or an [InvocationNotReadyError] when it has not completed
	// yet.
	Output(ctx context.Context) (O, error)
}

func InvocationById added in v0.21.0 

func InvocationById[O any](c *Client, invocationID string, opts ...InvocationHandleOption) InvocationHandle[O]

InvocationById returns a handle that lets you Attach or get Output of an invocation by its unique invocation ID. The invocation ID is returned when you submit an invocation (e.g., via Send or Submit methods).

Use this when you have an invocation ID and want to attach to the running invocation or retrieve its output. The output type O must match the handler's output type.

Example: 

handle := ingress.InvocationById[*MyOutput](client, "inv_1iHLUz0JfQwr0g3903tBTvJLIPSGwxDRjX")
output, err := handle.Attach(ctx)

func ObjectInvocationByIdempotencyKey added in v0.21.0 

func ObjectInvocationByIdempotencyKey[O any](c *Client, serviceName, objectKey, handlerName, idempotencyKey string, opts ...InvocationHandleOption) InvocationHandle[O]

ObjectInvocationByIdempotencyKey returns a handle that lets you Attach or get Output of a virtual object invocation by its idempotency key. This is useful when you submitted an invocation with an idempotency key and want to retrieve its result later.

The output type O must match the handler's output type.

Example: 

handle := ingress.ObjectInvocationByIdempotencyKey[*MyOutput](
    client, "MyObject", "object-123", "myHandler", "inv_1iHLUz0JfQwr0g3903tBTvJLIPSGwxDRjX")
output, err := handle.Attach(ctx)

func ServiceInvocationByIdempotencyKey added in v0.21.0 

func ServiceInvocationByIdempotencyKey[O any](c *Client, serviceName, handlerName, idempotencyKey string, opts ...InvocationHandleOption) InvocationHandle[O]

ServiceInvocationByIdempotencyKey returns a handle that lets you Attach or get Output of a service invocation by its idempotency key. This is useful when you submitted an invocation with an idempotency key and want to retrieve its result later.

The output type O must match the handler's output type.

Example: 

handle := ingress.ServiceInvocationByIdempotencyKey[*MyOutput](client, "MyService", "myHandler", "my-idempotency-key")
output, err := handle.Attach(ctx)

func WorkflowHandle added in v0.21.0 

func WorkflowHandle[O any](c *Client, serviceName, workflowID string, opts ...InvocationHandleOption) InvocationHandle[O]

WorkflowHandle returns a handle that lets you Attach or get Output of a workflow invocation. This is the primary way to interact with a workflow that has already been started.

The workflowID uniquely identifies the workflow instance. The output type O must match the workflow run handler's output type.

Example: 

handle := ingress.WorkflowHandle[*MyWorkflowOutput](client, "MyWorkflow", "workflow-123")
output, err := handle.Attach(ctx)

type InvocationHandleOption added in v0.25.0 

type InvocationHandleOption = options.IngressInvocationHandleOption

InvocationHandleOption is an option for resolving an invocation handle by id or idempotency key.

type InvocationNotFoundError 

type InvocationNotFoundError = ingress.InvocationNotFoundError

InvocationNotFoundError is returned when the invocation, service or handler was not found (HTTP 404). It is an Error; match it with errors.As.

type InvocationNotReadyError 

type InvocationNotReadyError = ingress.InvocationNotReadyError

InvocationNotReadyError is returned when the invocation exists but has not completed yet (HTTP 470), for example from an InvocationHandle's Output. It is an Error; match it with errors.As.

type RequestOption added in v0.25.0 

type RequestOption = options.IngressRequestOption

RequestOption is an option for a request made through the ingress.

type Requester 

type Requester[I any, O any] interface {
	// Request makes a synchronous invocation and blocks until the result is available.
	Request(ctx context.Context, input I, options ...RequestOption) (O, error)
	// Send makes an asynchronous invocation and returns immediately with a handle to retrieve the result later.
	Send(ctx context.Context, input I, options ...SendOption) (SendResponse[O], error)
}

Requester provides both synchronous (Request) and asynchronous (Send) invocation methods for Restate handlers. It requires both input (I) and output (O) type parameters.

Use Request to make a call and wait for the result. Use Send to make a fire-and-forget call that returns immediately with a SendResponse containing an InvocationHandle to retrieve the result later.

func NewRequester added in v0.21.0 

func NewRequester[I any, O any](c *Client, serviceName, handlerName string, key *string, codec *encoding.Codec) Requester[I, O]

func Object 

func Object[I any, O any](c *Client, serviceName, objectKey, handlerName string, opts ...options.ClientOption) Requester[I, O]

Object gets an ingress client for a Restate virtual object handler. This returns a Requester that supports both Request and Send operations.

Example: 

requester := ingress.Object[*MyInput, *MyOutput](client, "MyObject", "object-123", "myHandler")
// Call and wait for response:
output, err := requester.Request(ctx, &MyInput{...})
// Send request:
response, err := requester.Send(ctx, &MyInput{...})

func Service 

func Service[I any, O any](c *Client, serviceName, handlerName string, opts ...options.ClientOption) Requester[I, O]

Service gets an ingress client for a Restate service handler. This returns a Requester that supports both Request and Send operations.

Example: 

requester := ingress.Service[*MyInput, *MyOutput](client, "MyService", "myHandler")
// Call and wait for response:
output, err := requester.Request(ctx, &MyInput{...})
// Send request:
response, err := requester.Send(ctx, &MyInput{...})

func Workflow 

func Workflow[I any, O any](c *Client, serviceName, workflowID, handlerName string, opts ...options.ClientOption) Requester[I, O]

Workflow gets an ingress client for a Restate workflow handler. This returns a Requester that supports both Request and Send operations.

Example: 

requester := ingress.Workflow[*MyInput, *MyOutput](client, "MyWorkflow", "workflow-123", "myHandler")
// Call and wait for response:
output, err := requester.Request(ctx, &MyInput{...})
// Send request:
response, err := requester.Send(ctx, &MyInput{...})

type SendOption added in v0.25.0 

type SendOption = options.IngressSendOption

SendOption is an option for a one-way send made through the ingress.

type SendRequester 

type SendRequester[I any] interface {
	Send(ctx context.Context, input I, options ...SendOption) (SimpleSendResponse, error)
}

SendRequester is a simplified version of Requester that only supports Send operations (fire-and-forget). Unlike Requester, it does not require specifying the output type parameter, making it useful when you don't need to retrieve the invocation result.

If you need to later retrieve the output, use InvocationById with the Id() from SimpleSendResponse, or use Service/Object/Workflow functions instead which return SendResponse[O] with an InvocationHandle.

func ObjectSend 

func ObjectSend[I any](c *Client, serviceName, objectKey, handlerName string, opts ...options.ClientOption) SendRequester[I]

ObjectSend gets a send-only ingress client for a Restate virtual object handler.

This is a simplified version of Object that doesn't require the output type generic parameter. Use this when you only need to fire-and-forget invocations and don't need to retrieve results.

Example: 

requester := ingress.ObjectSend[*MyInput](client, "MyObject", "object-123", "myHandler")
response, err := requester.Send(ctx, &MyInput{...})
fmt.Println("Invocation ID:", response.Id())

func ServiceSend 

func ServiceSend[I any](c *Client, serviceName, handlerName string, opts ...options.ClientOption) SendRequester[I]

ServiceSend gets a send-only ingress client for a Restate service handler.

This is a simplified version of Service that doesn't require the output type generic parameter. Use this when you only need to fire-and-forget invocations and don't need to retrieve results.

Example: 

requester := ingress.ServiceSend[*MyInput](client, "MyService", "myHandler")
response, err := requester.Send(ctx, &MyInput{...})
fmt.Println("Invocation ID:", response.Id())

func WorkflowSend 

func WorkflowSend[I any](c *Client, serviceName, workflowID, handlerName string, opts ...options.ClientOption) SendRequester[I]

WorkflowSend gets a send-only ingress client for a Restate workflow handler.

This is a simplified version of Workflow that doesn't require the output type generic parameter. Use this when you only need to fire-and-forget invocations and don't need to retrieve results.

Example: 

requester := ingress.WorkflowSend[*MyInput](client, "MyWorkflow", "workflow-123", "myHandler")
response, err := requester.Send(ctx, &MyInput{...})
fmt.Println("Invocation ID:", response.Id())

type SendResponse added in v0.21.0 

type SendResponse[O any] interface {
	InvocationHandle[O]
	SimpleSendResponse
}

SendResponse is returned by Requester.Send and combines both SimpleSendResponse (for invocation metadata) and InvocationHandle (for retrieving the output).

You can use the embedded InvocationHandle methods (Attach/Output) to retrieve the invocation result, or use the SimpleSendResponse methods (Id/Status) to get invocation metadata.

type SimpleSendResponse added in v0.21.0 

type SimpleSendResponse interface {
	Id() string
	Status() string
}

SimpleSendResponse represents the result of a send-only invocation (fire-and-forget). It provides the invocation ID and status without requiring the output type parameter.

If you need to attach to the invocation later to retrieve its output, you can:

  1. Create an InvocationHandle using InvocationById with the Id() from this response, or
  2. Use Service/Object/Workflow functions instead of ServiceSend/ObjectSend/WorkflowSend, which return a full SendResponse[O] that includes an InvocationHandle.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.