Integração: tickets do Catena¶

Esta página é para o desenvolvedor de uma vitrine ou sistema de cobrança — o lugar onde você vende o acesso. Em vez de responder a um callback por cada espectador, você cria a sessão com antecedência e entrega ao espectador um ticket. O streamer admite o ticket por conta própria: verifica a assinatura, a validade e o escopo localmente, sem chamar os seus sistemas no caminho de reprodução.

A recompensa: a reprodução não depende mais da velocidade nem da disponibilidade da sua vitrine, os streams arrancam e trocam na hora, e não há um callback por espectador para escalar. Os seus sistemas são necessários no momento em que você vende o acesso — não enquanto o espectador assiste.

Criar uma concessão¶

Ao vender acesso, chame o management API para criar uma concessão (grant). O Catena assina um ticket (um JWT) e o devolve — o token é entregue apenas na criação; o registro guarda a concessão, não o ticket.

Autentique a chamada como você autentica qualquer requisição ao management API — com o login e a senha de administrador. Para que a sua vitrine nunca precise guardar credenciais de administrador completas, você pode em vez disso configurar no central uma chave de emissor (issuer key) dedicada — um token bearer cujo único poder é emitir e gerir concessões — e enviá-lo como Authorization: Bearer <issuer-key>.

POST /play-sessions/grants

{
  "streams": ["news", "arena"],
  "user_id": "subscriber-4821",
  "ttl_secs": 14400,
  "max_concurrent": 2,
  "bind_ip": "203.0.113.0/24",
  "note": "family plan"
}

A resposta carrega a concessão e o token. Entregue esse token ao reprodutor, que o apresenta na URL de reprodução como ?token=<jwt> (ou num cabeçalho Authorization: Bearer). Nada mais é pedido ao espectador — o streamer cuida do resto.

Modos de acesso¶

O campo access no corpo de POST /play-sessions/grants limita o que o ticket reproduz: o ao vivo, o arquivo ou parte do arquivo. Sem o campo, o ticket abre os streams por inteiro.

live abre ou fecha o ao vivo. archive aceita true (toda a gravação), false (arquivo fechado), uma profundidade depth_secs — quantos segundos de arquivo para trás a partir do momento atual — ou um intervalo from–to em segundos unix. O fim do intervalo pode estar no futuro: a gravação que cai no intervalo fica disponível à medida que é escrita.

O streamer aplica o modo a partir do próprio ticket, sem consultar o central nem os seus sistemas, em cada requisição:

• uma requisição fora do modo recebe 403; o resto da sessão continua funcionando;
• as playlists do arquivo, as janelas de gravação, a exportação e a leitura do arquivo por RTSP são recortadas à parte permitida; a reprodução do arquivo por RTSP termina no fim do intervalo;
• com o ao vivo fechado, as playlists e os protocolos ao vivo são recusados;
• os episódios de analítica só aparecem dentro do arquivo permitido;
• o VOD e a requisição info não são limitados pelo modo.

Um modo inválido é rejeitado com 422 e o caminho até o campo: um modo vazio ("live": false e "archive": false) — caminho access; profundidade junto com um intervalo, from não menor que to, profundidade zero ou um intervalo incompleto — caminho access.archive.

O modo é definido na emissão e não muda: PATCH com o campo access é rejeitado com 422. Para outro modo, emita uma nova concessão.

O modo é aplicado pelos streamers da versão atual. Um streamer da versão anterior não conhece o campo access e admite o ticket no stream inteiro, então atualize primeiro os streamers e depois comece a emitir concessões com modo. Os campos do modo que o streamer não conhece são ignorados; os conhecidos são aplicados.

A concessão com modo é emitida pela sua vitrine ou middleware pela API, ou por um operador à mão: na página do stream no console, o formulário «Emitir um ticket de reprodução» tem o campo «Acesso» com «Tudo», «Somente ao vivo», «Somente arquivo», «Ao vivo e arquivo», e para o arquivo «Toda a gravação», «Últimas N horas» ou «Intervalo»; a recusa do servidor aparece no campo. A vitrine da Catena ainda não emite concessões com modo aos assinantes.

Telas¶

max_concurrent limita quantas telas consomem ativamente o ticket ao mesmo tempo — uma casa com dois televisores, por exemplo. Passe do limite e a tela mais antiga é cortada; a mais nova vence. Você pode mudar o limite depois sem reemitir o ticket, porque ele vive no registro, não no token assinado:

PATCH /play-sessions/grants/{jti}
{ "max_concurrent": 3 }

Revogar¶

Cancele uma concessão e cada streamer solta os seus espectadores em segundos e recusa o ticket dali em diante — o cancelamento viaja aos streamers por um feed de revogação, não esperando o ticket expirar. Não há reautorização para as sessões de ticket; a revogação é o único stream que as termina antes do tempo.

Roaming¶

Um espectador cujo endereço muda — um telefone que sai do Wi-Fi para os dados móveis — é admitido de novo no novo endereço, offline, enquanto a sessão antiga morre por inatividade. Conta como um único percurso, não como uma nova cobrança, agrupado pela concessão. Se você definir bind_ip, o roaming fica dentro dessa faixa.

Listagem e status¶

GET /play-sessions/grants lista as concessões e o seu status — issued (entregue, ainda não reproduzida), played (usada ao menos uma vez), revoked, expired —, filtrável por user_id e status. É o registro do que você vendeu e se foi usado.

Migre no seu ritmo¶

Os tickets e um backend existente correm lado a lado — tickets para uns espectadores, o callback para outros — então você pode mover audiência por audiência. O estado final é o interruptor opaque_tokens: false na política de autorização: uma vez definido, qualquer token que não seja um ticket é recusado de imediato, sem consultar listas nem um backend, e a via do callback fica fechada de vez.

Próximos passos¶

• Proteger a reprodução — a mesma política vista pelo operador.
• Ciclo de vida da sessão — como uma sessão de ticket abre, fecha e sobrevive a um tropeço do cluster.
• autorização flussonic — a via de callback da qual você migra.