Convites iCalendar: UID, SEQUENCE e como acertar nos fusos horários

O que é

O iCalendar (RFC 5545, tipo de mídia text/calendar) descreve eventos como componentes VEVENT dentro de um VCALENDAR. O iTIP (RFC 5546) define como eles são trocados: METHOD:REQUEST enviado pelo organizador, METHOD:REPLY enviado pelos participantes com um PARTSTAT (aceito, recusado, provisório) e METHOD:CANCEL para retirar o evento. Um evento é identificado em todas as mensagens pelo UID; uma revisão, pelo SEQUENCE, que o organizador deve incrementar quando altera DTSTART, DTEND, DURATION, RRULE e propriedades semelhantes. Os horários têm três formas: UTC (20260916T090000Z), hora local com o parâmetro TZID, que remete a um componente VTIMEZONE no mesmo objeto (DTSTART;TZID=Europe/Zurich:20260916T110000), e hora flutuante, sem nenhum dos dois, que significa "11:00 onde quer que o leitor esteja". A RFC 5545 exige um VTIMEZONE para cada TZID usado e alerta que omiti-lo leva a interpretações inconsistentes da hora local.

Por que importa

Um convite que chega com uma hora de diferença após a mudança do horário de verão, ou que cria um duplicado a cada atualização, é pior do que nenhum convite. Calendários são um dos casos em que "guardar em UTC" não basta: uma reunião semanal às 09:00 em Zurique deve continuar às 09:00 locais nas transições de março e outubro, e isso só é expresso por uma hora local ancorada ao fuso.

Como aplicar

• Gere um UID estável para cada evento, armazene-o, reutilize-o em todas as atualizações e cancelamentos e incremente o SEQUENCE a cada alteração substantiva; o DTSTAMP é o momento da mensagem, não o contador de revisões.
• Use TZID com nomes de fuso da IANA e incorpore um VTIMEZONE correto (com regras STANDARD e DAYLIGHT) obtido de uma biblioteca mantida. Use UTC para eventos únicos com participantes em vários fusos e hora flutuante apenas para o que realmente segue o relógio de parede do leitor; eventos de dia inteiro usam um valor DATE (DTSTART;VALUE=DATE:20260916) em vez de uma meia-noite flutuante.
• Em eventos recorrentes, siga a RFC 5545: quando o DTSTART tem um TZID, a parte UNTIL da regra deve estar em UTC. Modifique ocorrências individuais com RECURRENCE-ID em vez de editar a série.
• Envie os convites como uma parte text/calendar com o parâmetro method definido (method=REQUEST) e inclua o mesmo objeto como anexo .ics para os clientes que ignoram o parâmetro.
• Faça testes de ida e volta com pelo menos duas famílias de clientes através de uma fronteira de horário de verão, incluindo uma atualização e um cancelamento.

Armadilhas

Um novo UID a cada atualização (gera duplicados). Nomes de fuso que não são identificadores da IANA, que outros clientes não conseguem mapear. Cancelar com STATUS:CANCELLED sem METHOD:CANCEL. Eventos de dia inteiro enviados como meia-noite a meia-noite em UTC, que se deslocam um dia em outros fusos. Enviar um CANCEL sem incrementar o SEQUENCE, o que a RFC 5546 exige.