ingress

package
v1.0.1 Latest Latest
Warning

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

 Go to latest Published: Jul 13, 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 InvocationHandle 

type InvocationHandle[O any] interface {
	// Attach calls the attach API and blocks until the output is available. Returns an
	// InvocationNotFoundError if the invocation does not exist.
	Attach(ctx context.Context) (O, error)
	// Output calls the attachment API and returns the output if available, otherwise returns an
	// InvocationNotFoundError if the invocation does not exist or an InvocationNotReadyError if
	// the invocation is not complete.
	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

type InvocationNotReadyError 

type InvocationNotReadyError = ingress.InvocationNotReadyError

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.