> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Stream em tempo real

> Assine eventos ao vivo da aplicação através de um stream de Server-Sent Events (SSE).

`api.ApplicationRealtime(appID)` abre um stream de [Server-Sent Events](https://developer.mozilla.org/docs/Web/API/Server-sent_events) e retorna um `*rest.RealtimeStream`. Itere sobre ele com `stream.Next()` até `io.EOF`.

```go theme={null}
client := rest.NewClient(os.Getenv("SQUARECLOUD_API_KEY"))
defer client.Close()

api := rest.New(client)
```

## Consumindo o stream

```go theme={null}
stream, err := api.ApplicationRealtime("abc123def456abc123def456")
if err != nil {
	panic(err)
}
defer stream.Close()

for {
	event, err := stream.Next()
	if err == io.EOF {
		break // stream encerrado (ex.: TTL de 10 minutos atingido)
	}
	if err != nil {
		panic(err)
	}

	fmt.Println(event.Name, string(event.Data))
}
```

Sempre use `defer stream.Close()` — um stream não fechado mantém ocupado um dos slots de conexão da sua conta.

## Formato do evento

O stream emite dois tipos de frames:

* **Eventos de sistema** — mensagens do ciclo de vida da conexão: `REALTIME_CONNECTING`, `REALTIME_TIMEOUT`, `REALTIME_DISCONNECTED`, `REALTIME_RECONNECT` e `REALTIME_ERROR`.
* **Eventos `message`** — o payload da aplicação. `Data` é opaco para o SDK, geralmente JSON — faça o unmarshal você mesmo:

```go theme={null}
if event.Name == "message" {
	var payload map[string]any
	if err := json.Unmarshal(event.Data, &payload); err == nil {
		fmt.Println(payload)
	}
}
```

## Limites de conexão

<Warning>
  Uma única conta pode manter no máximo **5 conexões simultâneas** abertas, e cada conexão dura até **10 minutos** (seu TTL). Quando o TTL é atingido, o stream encerra com `io.EOF` — reconecte em um loop para continuar assinando.
</Warning>

```go theme={null}
for {
	stream, err := api.ApplicationRealtime("abc123def456abc123def456")
	if err != nil {
		panic(err)
	}

	for {
		event, err := stream.Next()
		if err != nil {
			break // io.EOF no TTL — reconecte
		}
		fmt.Println(event.Name, string(event.Data))
	}

	stream.Close()
}
```

## Cancelamento

Anexe um `context.Context` com `rest.WithContext` para encerrar o stream de fora:

```go theme={null}
ctx, cancel := context.WithCancel(context.Background())
defer cancel()

stream, err := api.ApplicationRealtime("abc123def456abc123def456", rest.WithContext(ctx))
if err != nil {
	panic(err)
}
defer stream.Close()

// cancel() a partir de outra goroutine encerra o stream
```