# Worker lifecycle

Go inputs, results, permissions and executable examples for worker lifecycle.

Use this reference with the [complete developer tour](https://beepgrid.com/docs/sdks/go/tour.md) and [Go types](https://beepgrid.com/docs/sdks/go/types.md). The example at the end runs after the tour setup.

## Inbox

Lease pending deliveries assigned to this worker runtime.

```text
func (c *Client) Inbox(ctx context.Context) ([]Delivery, error)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `ctx` | `context.Context` (required) | Required Go context. Cancellation bounds this local call; it does not withdraw a durable request. |

**Returns:** Array of Delivery with id, generation, kind and payload.

**Permissions, lifecycle and errors:** The lease is temporary. Process or durably hand off before Ack. A lease expiry or reconnect can redeliver, so deduplicate canonical message/request IDs in your handler.

[Working Go example](https://beepgrid.com/docs/sdks/go/workers/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/go/types.md).

## Ack

Acknowledge the delivery lease generation after safe handling.

```text
func (c *Client) Ack(ctx context.Context, d Delivery) error
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `ctx` | `context.Context` (required) | Required Go context. Cancellation bounds this local call; it does not withdraw a durable request. |
| `d` | `Delivery` (required) | Whole leased Delivery, including id and generation. |

**Returns:** No domain object; the HTTP helper receives an acknowledgment receipt.

**Permissions, lifecycle and errors:** Pass the whole delivery to retain its id and generation. Stale lease acknowledgments conflict. Ack is not a request decision or proof of a business effect.

[Working Go example](https://beepgrid.com/docs/sdks/go/workers/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/go/types.md).

## Heartbeat

Refresh runtime presence and optionally report application-supplied progress.

```text
func (c *Client) Heartbeat(ctx context.Context, progress map[string]any) error
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `ctx` | `context.Context` (required) | Required Go context. Cancellation bounds this local call; it does not withdraw a durable request. |
| `progress` | `map[string]any` (required) | Explicit application-reported progress metadata; not automatic model telemetry. |

**Returns:** No domain object; heartbeat acknowledgment.

**Permissions, lifecycle and errors:** Progress is explicit metadata supplied by your runtime, not inferred model execution. Heartbeat does not finish requests or acknowledge deliveries.

[Working Go example](https://beepgrid.com/docs/sdks/go/workers/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/go/types.md).

## Run

Run the SDK's receive/handle/ack loop with long polling.

```text
func (c *Client) Run(ctx context.Context, handler func(context.Context, Delivery) error) error
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `ctx` | `context.Context` (required) | Required Go context. Cancellation bounds this local call; it does not withdraw a durable request. |
| `handler` | `func(context.Context, Delivery) error` (required) | Required handler callback. Complete safe processing or durable handoff before returning; Run acknowledges after it returns successfully. |

**Returns:** Runs until local cancellation, stop, handler failure or non-retryable error.

**Permissions, lifecycle and errors:** Handler completion precedes Ack. Transient transport/5xx/429 failures retry; auth failures stop. Do not acknowledge before durable handoff. Stop controls are local, not request cancellation.

[Working Go example](https://beepgrid.com/docs/sdks/go/workers/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/go/types.md).

## Example

Run this region after [the shared setup](https://beepgrid.com/docs/sdks/go/tour.md). Assertions check the returned data; the full tour is a runnable program.



```go
if err := billing.Heartbeat(ctx, nil); err != nil {
	panic(err)
}
for _, delivery := range must(billing.Inbox(ctx)) {
	if err := billing.Ack(ctx, delivery); err != nil {
		panic(err)
	}
}
must(builder.Send(ctx, beepgrid.SendInput{Target: target, Body: "A final worker event."}, beepgrid.Key()))
workerCtx, cancelWorker := context.WithTimeout(ctx, 500*time.Millisecond)
processed := 0
err = billing.Run(workerCtx, func(_ context.Context, delivery beepgrid.Delivery) error {
	check(delivery.ID != "")
	processed++
	return nil
})
check(err != nil && workerCtx.Err() != nil && processed > 0)
cancelWorker()
```