isar-sync #

Isar를 위한 오프라인 퍼스트 동기화 프레임워크

Install #

dependencies:
  isar_sync: ^0.1.0-dev.1

Flutter에서 빠르게 추가:

flutter pub add isar_sync

Flutter Companion #

Flutter 전용 통합(google_sign_in, icloud_storage)이 필요하면 companion 패키지를 사용하세요.

companion 패키지: packages/isar_sync_flutter
companion 문서: doc/flutter-companion.md
e2e Flutter 예제: packages/isar_sync_flutter/example
멀티 기기 동기화 데모(isar_community + isar_sync_flutter): examples/notes_multi_device

Quick Start #

import 'package:isar_sync/isar_sync.dart';

final queue = InMemorySyncQueue();
final store = InMemorySyncStore();
final cursorStore = InMemorySyncCursorStore();
final conflictResolver = const LastWriteWinsConflictResolver();

final applyEngine = DefaultApplyEngine(
  store: store,
  conflictResolver: conflictResolver,
);

// Replace with a real adapter (GoogleDriveSyncAdapter or ICloudSyncAdapter).
final adapter = MySyncAdapter();

final syncCore = SyncCore(
  queue: queue,
  adapter: adapter,
  applyEngine: applyEngine,
  cursorStore: cursorStore,
);

await syncCore.syncOnce();

Adapter Setup #

Google Drive setup: doc/google-drive-setup.md
Apple iCloud setup: doc/icloud-setup.md
Isar integration guide: doc/isar-integration.md

같은 Google 계정 또는 같은 Apple ID로 로그인된 다른 기기에서 동일 namespace를 사용하면, 해당 원격 저장소를 통해 이벤트를 공유하고 Isar 상태를 동기화할 수 있습니다.

Publish Docs #

pub 배포 가이드: doc/publish-to-pub.md

Detailed Docs #

기능 상세: doc/features.md
사용법(엔드투엔드): doc/usage.md
Flutter companion: doc/flutter-companion.md
Isar 통합: doc/isar-integration.md
컬렉션 매핑 템플릿: doc/collection-mapping-template.md
템플릿 코드 파일: example/isar_collection_mapping_template.dart

1. Why #

문제 정의 #

Isar Database는 훌륭한 로컬 DB이지만, 앱이 성장할수록 아래 공백이 드러납니다.

멀티 디바이스 동기화 부재
변경 기록(change log) 부재
협업/공유 기능 구현 난이도 증가

실무에서는 결국 다음 선택지로 이동합니다.

Firebase 등을 추가하여 구조가 복잡해짐
동기화를 직접 구현하여 재사용성 낮고 유지보수 비용 증가
서버 운영 부담 발생

핵심 문제는 다음 한 문장으로 요약됩니다.

로컬 퍼스트는 좋지만, 그 다음 단계가 비어 있다.

isar-sync의 동기 #

isar-sync는 Isar를 대체하지 않습니다. Isar를 그대로 유지한 채 동기화 능력을 추가합니다.

서버 없이도 시작 가능
필요 시 선택적으로 확장 가능
기존 코드의 변경 최소화

2. What #

핵심 목표 #

Isar 기반 앱에 동기화 기능을 추가할 수 있는 범용 프레임워크

구체적 목표 #

로컬 퍼스트 유지

Isar를 항상 source of truth로 유지

서버 강제 없음

특정 백엔드 종속 제거
다양한 저장소/전송 방식 지원

확장 가능한 구조

Adapter 플러그인 구조
Conflict 전략 교체 가능

최소 침투성

기존 도메인/저장 코드의 대규모 변경 없이 도입 가능

하지 않는 것 #

Firebase 수준의 완전 자동 동기화 보장
강한 실시간 일관성 보장
완전무결한 충돌 해결 보장

대신 다음을 제공합니다.

단순하고 예측 가능한 sync

3. Conceptual Model #

1) State vs Change #

Isar: 현재 상태(State)
isar-sync: 변화 기록(Change)

이 분리가 디버깅, 재처리, 재동기화의 기반입니다.

2) Event-driven #

모든 데이터 변경은 이벤트로 캡처됩니다.

State 변경 -> Event 생성 -> 동기화

3) Eventually Consistent #

즉시 일치: 목표 아님
결국 일치: 목표

4. End-to-End Flow #

로컬 변경 발생

사용자 액션으로 데이터 수정

Change Capture

Isar write와 SyncEvent 생성을 동일 트랜잭션으로 처리
데이터와 이벤트의 원자성 보장

로컬 큐 적재

SyncEvent를 SyncQueue에 저장
아직 외부 저장소에는 미반영

Push

SyncQueue -> Adapter -> 외부 저장소

Pull

외부 저장소 -> Adapter -> 이벤트 수신

정렬/필터링

중복 제거
timestamp 기반 정렬

Apply

event를 Isar에 반영 (upsert/delete)

UI 반영

Isar watch를 통해 UI 자동 갱신

Flow Diagram (Mermaid) #

flowchart LR
	U[User Action] --> W[Isar Write]
	W --> C[Change Capture]
	C --> E[SyncEvent 생성]
	E --> Q[SyncQueue 적재]
	Q --> P[Push]
	P --> A1[Adapter]
	A1 --> R[(Remote Storage)]

	R --> A2[Adapter]
	A2 --> PL[Pull]
	PL --> F[중복 제거/정렬]
	F --> AP[Apply Engine]
	AP --> I[Isar 업데이트]
	I --> UI[UI 자동 반영]

5. Components #

1) Sync Core #

전체 오케스트레이션

2) Change Capture Layer #

이벤트 생성
트랜잭션 통합

3) Sync Queue #

업로드 대기열
retry/backoff

4) Adapter Layer #

외부 저장소와의 연결 추상화

5) Apply Engine #

이벤트를 상태로 반영

6) Conflict Resolver #

충돌 해결 정책 캡슐화

6. Design Principles #

단순성 우선 #

복잡한 CRDT보다 이해 가능한 구조 우선

예측 가능성 #

overwrite 규칙과 적용 순서를 명시적으로 유지

디버깅 가능성 #

이벤트 로그 중심 추적 가능성 확보

점진적 확장 #

v1: 단순 동기화
v2: 고급 정책/최적화 확장

7. Essence #

이 프로젝트의 본질은 단순 유틸리티가 아닙니다.

로컬 DB를 분산 시스템으로 확장하는 레이어

정리하면,

Isar는 상태를 저장한다.
isar-sync는 변화를 기록하고 공유한다.

One-liner #

isar-sync = Isar를 위한 오프라인 퍼스트 동기화 프레임워크

Status #

Draft concept (v0)

Initial Implementation Direction (v1) #

v1은 아래 원칙으로 구현합니다.

단일 디바이스/멀티 디바이스에서 예측 가능한 동기화 루프 제공
push/pull 분리 및 배치 처리
명시적인 conflict 전략(기본 Last Write Wins)
Adapter 교체 가능한 포트-어댑터 구조

예상 모듈 구성:

Sync Core: sync orchestration
Sync Queue: 이벤트 적재/재시도
Adapter: 원격 저장소 연결
Apply Engine: 원격 이벤트를 로컬 상태로 반영
Conflict Resolver: 충돌 판단/결정

isar_sync 0.1.0-dev.1 isar_sync: ^0.1.0-dev.1 copied to clipboard

Metadata