ikieEngineeringGet started
All posts

동기화캘린더설계

외부 캘린더와는 칸마다 세 쪽을 견줘 합쳐요

같은 일정을 Google과 ikie 양쪽에서 고쳐도 두 고침이 모두 남도록, ikie는 마지막으로 맞춘 값을 기억해 두고 칸 묶음마다 세 쪽을 견줘 합쳐요. 엔진 하나가 Google·iCloud·Outlook·iPhone 캘린더·.ics 구독을 이렇게 맞추고, 우리가 모르는 칸은 버리지 않아요.

English

ikie는 Google 캘린더, iCloud(CalDAV), Outlook, iPhone의 캘린더, .ics 주소 구독을 잇고 양쪽으로 맞춰요. 잇는 순간부터 같은 일정이 두 곳에 있게 돼요. 아침에 휴대폰의 ikie에서 회의 시간을 30분 미뤘는데, 그사이 동료가 Google에서 회의 제목을 고쳤다고 해 봐요. 다음 맞추기에서 무엇이 남아야 할까요?

답은 둘 다예요. 시간은 우리 것, 제목은 Google 것이 남아야 해요. 이 글은 그렇게 남기려고 정한 규칙과, 그 규칙을 지키다 부딪힌 것들을 적어요.

한쪽으로 덮으면 하나를 잃어요

가장 쉬운 방법은 "나중에 고친 쪽이 이긴다"예요. 일정 하나를 한 덩어리로 보고, 고친 때가 늦은 쪽으로 통째로 덮어요. 위의 예에서 동료가 나중에 고쳤다면 제목은 맞지만 우리가 미룬 시간이 원래대로 돌아가요. 사용자가 보기에는 고친 것이 아무 까닭 없이 되돌아간 거예요.

일정을 칸마다 나눠 견주면 대부분 풀려요. 다만 칸마다 "누가 바꿨나"를 알려면 두 쪽만으로는 모자라요. 지금 우리 값과 지금 외부 값이 다르다는 것만으로는 우리가 바꿨는지 외부가 바꿨는지 알 수 없어요. 그래서 세 번째 값이 필요해요.

세 쪽: 기준, 우리, 외부

ikie는 외부 일정 하나마다 연결 기록(binding)을 한 줄 두고, 거기에 마지막으로 양쪽이 같았던 값을 적어 둬요. 이것이 기준이에요. 맞출 때는 기준과 우리 값, 기준과 외부 값을 따로 견줘요. 기준과 다른 쪽이 바꾼 쪽이에요.

묶음기준(마지막으로 맞춘 값)우리(ikie)외부(Google)합친 값
제목주간 회의주간 회의주간 회의 (2층)주간 회의 (2층)외부만 바꿈
시간10:00–11:0010:30–11:3010:00–11:0010:30–11:30우리만 바꿈
장소회의실 A회의실 B회의실 C나중에 고친 쪽둘 다 바꿈: 부딪힘으로 셈
메모안건 정리안건 정리안건 정리안건 정리아무도 안 바꿈
칸 묶음마다 세 쪽을 견줘요. 기준과 다른 칸(강조)이 바꾼 쪽이에요. 한쪽만 바꿨으면 그쪽을, 둘 다 바꿨으면 나중에 고친 쪽을 고르고 부딪힘으로 세요.

규칙은 세 줄이에요. 우리가 안 바꿨으면 외부 값을, 외부가 안 바꿨으면 우리 값을 둬요. 둘 다 바꿨으면 나중에 고친 쪽을 골라요. 이 판단은 데이터베이스도 네트워크도 모르는 순수 함수 하나가 해요.

export function merge3(base, local, remote, localNewer): MergeResult {
  if (!base) return { merged: remote, conflicts: [] };
  const merged = { ...remote };
  const conflicts: SyncUnit[] = [];
  for (const u of PUSH_UNITS) {
    const localChanged = unitKnown(u, base) && !unitSame(u, base, local);
    const remoteChanged = !unitSame(u, base, remote);
    const takeLocal = localChanged && (!remoteChanged || localNewer);
    if (localChanged && remoteChanged && !unitSame(u, local, remote)) conflicts.push(u);
    if (takeLocal) for (const k of SYNC_UNITS[u]) merged[k] = local[k];
  }
  return { merged, conflicts };
}

둘 다 바꿨어도 값이 같으면 부딪힘으로 세지 않아요. 두 사람이 같은 오타를 함께 고친 경우예요. 처음 받는 일정은 기준이 없으니 외부 값을 그대로 받아요.

"나중"은 고친 시각으로 정해요. 우리 쪽 고친 때는 Postgres의 시각 정밀도인 마이크로초로 읽어요. 같은 밀리초 안에 일어난 두 고침도 가를 수 있게요. 외부가 고친 때를 알려 주지 않으면 마지막으로 맞춘 때와 견줘요.

칸은 묶음으로 합쳐요

칸 하나하나를 따로 합치면 안 되는 경우가 있어요. 시작은 우리 것, 끝은 외부 것을 고르면 끝이 시작보다 앞선 일정이 생길 수 있어요. 그래서 함께 바뀌어야 하는 칸은 묶음(unit) 하나로 다뤄요.

묶음칸
시간시간 종류, 시작·끝 날짜, 시작·끝 시각, 시작·끝 시간대
반복반복 규칙(RRULE), 더한 날(RDATE), 뺀 날(EXDATE)
나머지 열둘종류, 제목, 메모, 장소, 링크, 색, 바쁨 표시, 공개 범위, 회의 링크, 알림, 이동 시간, 내 응답

묶음은 열네 개예요. 이 중 종류와 회의 링크는 받기만 해요. Google은 만든 뒤 일정 종류를 바꾸지 못하게 하고, 회의 링크는 외부가 만들어 주는 값이라서요.

나중에 새 묶음을 더할 때도 이 구조가 도와줘요. 알림을 동기화하기 시작했을 때, 그 전에 적어 둔 기준에는 알림 칸이 없었어요. 그대로 견주면 기준에 칸이 없다는 것만으로 모든 일정이 "우리가 알림을 바꿨다"로 읽히고, 첫 맞추기에서 외부의 알림을 우리 값으로 덮어 보내게 돼요. 그래서 기준에 없는 묶음은 우리가 바꾼 것으로 보지 않고, 처음 한 번은 외부 값을 따르게 했어요.

우리가 모르는 칸은 버리지 않아요

외부 캘린더에는 ikie가 모르는 칸이 많아요. Apple은 X-APPLE-…로 시작하는 칸을 적고, Google 일정에는 첨부·메일 알림·다른 앱이 남긴 숨은 값이 붙어요. 우리가 아는 칸만 골라 일정을 다시 써서 보내면 이것들이 모두 사라져요.

그래서 받은 응답을 원본 그대로(raw) 연결 기록에 함께 둬요. 보낼 때는 바뀐 묶음만 보내요.

  • Google은 바뀐 묶음의 칸만 PATCH해요. Google이 통째로 바꾸는 칸은 받은 원본과 합쳐 보내요. 숨은 확장 칸에서는 우리 키만 고치고 다른 앱의 키는 그대로 두고, 참석자 목록에서는 내 응답 줄만 바꾸고 다른 사람의 응답은 받은 그대로 보내요.
  • CalDAV(iCloud·네이버)는 받은 .ics 파일을 열어 바뀐 묶음만 고쳐 써요. 모르는 칸과 따로 고친 회차는 손대지 않아요. 순서 번호(SEQUENCE)는 시간이나 반복을 바꿀 때만 올려요. 그 밖의 고침은 참석자에게 다시 알릴 일이 아니니까요.

이것은 시험이 지켜요. 매주 반복하는 iCloud 일정의 제목과 장소만 고친 뒤, 결과 파일에 Apple의 X-APPLE-TRAVEL-ADVISORY-BEHAVIOR:AUTOMATIC 줄과 따로 고친 회차 둘이 그대로 있는지, 순서 번호를 올리지 않았는지 봐요.

외부가 담지 못하는 칸도 있어요. iPhone의 캘린더는 색·공개 범위·이동 시간을 담지 못해요. 이런 칸은 받은 값 대신 기준 값을 둬서 "외부가 지웠다"로 읽지 않아요. 그래서 우리 쪽 값이 남아요. 무엇을 못 담는지는 손으로 적지 않고, 칸마다 외부 대응을 적은 모델 선언에서 읽어요. Outlook처럼 알림을 하나만 담는 외부는 양쪽 알림을 외부가 담는 만큼만 견줘서, 담지 못한 나머지 알림을 지워진 것으로 보지 않아요.

엔진 하나, 어댑터 여럿

맞추는 엔진은 하나예요. 엔진은 외부가 무엇인지 모르고, 포트(CalendarPort)라는 모양만 알아요.

export interface CalendarPort {
  unsupported?: readonly SyncUnit[];
  alarmSlots?: number;
  calendars(): Promise<RemoteCalendar[]>;
  changes(cal: CalendarRef, known: StoredEvent[]): Promise<RemoteChanges>;
  get(cal: CalendarRef, ev: StoredEvent): Promise<RemoteEvent | null>;
  create(cal: CalendarRef, fields: SyncFields): Promise<RemoteEvent>;
  update(cal, ev, fields, units: SyncUnit[], occurrences: OccurrenceOut[]): Promise<RemoteEvent>;
  remove(cal: CalendarRef, ev: StoredEvent): Promise<void>;
}

외부마다 다른 것은 "바뀐 것을 어떻게 알아내나"뿐이에요. 그 차이는 어댑터 안에 숨겨요.

외부바뀐 것을 알아내는 법
Google증분 토큰(syncToken). 처음은 지난 365일부터 모두
iCloud·네이버(CalDAV)캘린더 판(ctag)과 RFC 6578 동기화 토큰
OutlookGraph의 증분은 펼친 회차만 줘서 시리즈를 담지 못해요. 그래서 일정 목록의 id·changeKey를 우리가 기억한 판과 견줘요
iPhone 캘린더서버가 기기를 부를 수 없어 기기가 시리즈마다 .ics 한 장과 내용 해시를 올려요. 우리가 보낼 고침은 기기가 받아 적용해요
.ics 구독받기만 해요. UID마다 나누고, 받을 때마다 바뀌는 DTSTAMP를 뺀 해시로 판을 비교해요

보낼 때는 세 외부(Google·CalDAV·Outlook) 모두 "내가 본 판일 때만 고쳐라"(If-Match)를 붙여요. 그사이 외부가 바뀌어 거절(412)되면 그 일정 하나만 다시 받아 합치고, 합친 값에 남은 우리 고침은 다음 맞추기에 보내요.

반복 일정의 회차

반복 일정은 시리즈 하나와 회차의 예외로 와요. 회차의 주소는 ikie 안에서처럼 원래 시작이에요(반복 일정은 저장하지 않아요). Google은 회차 예외를 따로 된 일정처럼 보내요. 그래서 시리즈를 먼저 적용하고 예외를 그 뒤에 붙여요. CalDAV는 예외가 같은 파일 안에 RECURRENCE-ID로 와요.

회차를 보낼 때도 칸 묶음 규칙이 그대로예요. 회차마다 그 회차의 기준을 따로 두고, 그 기준과 달라진 묶음만 보내요. 이 규칙은 버그에서 왔어요. 남이 주최한 반복 회의의 한 회차에 "참석"으로 답하면, 바꾸지도 않은 시간과 상태까지 함께 보냈어요. Google은 주최자가 아닌 사람의 시간 고침을 거절했고, 함께 보낸 응답까지 통째로 거절됐어요. 회차의 기준과 견줘 응답만 보내도록 고친 뒤로 응답이 올라가요.

부딪히며 고친 것

  • 한 번 안 보인 것이 지운 것은 아니에요. iPhone에서 고른 캘린더를 바꾸거나 캘린더 권한을 잃으면, 그 캘린더가 올리기에서 빠져요. 예전에는 이것을 "일정이 모두 지워졌다"로 읽었어요. 지금은 빠진 캘린더를 지우지 않고, 지운 것으로 보는 범위도 기기가 실제로 읽은 기간 안쪽으로 줄였어요. .ics 구독이 너무 커서 앞의 5,000개만 받았을 때도 같아요. 잘렸다고 적고, 그때는 아무것도 지우지 않아요.
  • 보관한 원본이 없으면 다시 받아요. CalDAV 일정의 원본 .ics가 없을 때 새로 만들어 덮어쓰면, 일정의 정체(UID)와 모르는 칸을 함께 잃어요. 지금은 그 일정을 다시 받아 그 위에 고쳐 써요.
  • 같은 시각도 글자가 다를 수 있어요. Google에서 회차를 원래 시작(UTC)으로 찾으면 빈 결과가 왔어요. Google이 같은 시각을 시간대 오프셋을 붙인 글자로 적어서였어요. 회차 고침이 조용히 건너뛰어졌죠. 지금은 회차 id로 먼저 읽고, 없으면 그날 앞뒤 회차 중 원래 시작이 같은 것을 골라요.
  • 느린 것은 계산이 아니라 왕복이었어요. 맞추기 한 번에 17초가 걸린 적이 있어요. CPU는 0.2초였어요. 나머지는 캘린더를 하나씩 차례로 받으며 쌓인 외부 왕복이었어요(Google 계정 하나에 약 19번). 지금은 캘린더를 넷씩 함께 받고, 하나가 실패해도 나머지는 끝까지 맞춰요.

하지 못하는 것은 거절해요

모든 것을 맞추지는 못해요. 그럴 때는 반쯤 맞추지 않고 분명히 거절해요.

  • 외부와 이은 반복 일정을 "이 회차와 이후 모두"로 나누는 것은 409로 거절해요. 나눈 뒤 외부의 회차가 어느 시리즈의 것인지 지금 엔진이 보장하지 못해서예요.
  • 다른 항목 안에 넣은 일정, 시간대 없는 시각(floating), 시간 없는 할 일은 외부로 보내지 않아요. 외부 캘린더에 맞는 자리가 없어요.
  • iPhone 캘린더가 담지 못하는 반복(RDATE, 지원하지 않는 반복 단위)은 낮춰서 보내지 않고 아예 보내지 않아요.

배운 것

외부 캘린더를 맞추는 일의 대부분은 "누가 무엇을 바꿨나"를 정확히 아는 일이었어요. 그걸 위해 마지막으로 맞춘 값을 사실로 적어 두고, 함께 바뀌는 칸을 묶고, 판단은 순수 함수 하나에 모았어요. 외부마다 다른 것은 바뀐 것을 알아내는 법뿐이라 어댑터 안에 숨겼어요. 그리고 모르는 것은 버리지 않았어요. 사용자가 다른 앱에서 붙인 것을 우리가 모른다는 까닭으로 지우면, 그 앱에서는 ikie가 망가뜨린 거니까요.

The ikie teamikie is a calendar for your events and to-dos in one place. Here we write about the problems we run into while building it, and how we solve them.