Backend Çalışma Zamanı ve Adaptörler

@copypatch/backend paketi, CopyPatch v3’ün harici süreç gerektirmeyen gömülü çekirdeğidir. Standart Web Request/Response hattı üzerinde rota yönlendirmeyi, yetkilendirmeyi, CSRF denetimlerini ve iyimser revizyon koordinasyonunu yönetir.

1. Backend Çalışma Zamanını Başlatma

İstediğiniz depolama adaptörü ve kimlik doğrulama stratejisi ile backend nesnesini oluşturun:

lib/copypatch.ts

import { createCopyPatchBackend } from '@copypatch/backend';
import { createSQLitePersistence } from '@copypatch/storage-sqlite';

const persistence = createSQLitePersistence('./copypatch.sqlite');
await persistence.migrate();

const copypatch = createCopyPatchBackend({
  persistence,
  passphraseHash: process.env.COPYPATCH_PASSPHRASE_HASH!,
});

2. Kimlik Doğrulama Stratejileri

createCopyPatchBackend birbirinden bağımsız iki stratejiden tam olarak birini kabul eder:

Strateji A: Dahili Parola Oturumu (`passphraseHash`)

Mevcut kullanıcı veritabanı olmayan projeler için CopyPatch tarafından tamamen bağımsız yönetilir.
Argon2id parola özeti (RFC 9106 önerilen parametreleri) kullanır.
HttpOnly, SameSite=Strict oturum çerezleri ve çift belirteçli (dual-token) CSRF koruması üretir.
Müşteri teslimatları, ajans projeleri ve pazarlama web siteleri için idealdir.

Strateji B: Host Kimlik Doğrulama Adaptörü (`authAdapter`)

Kullanıcı çözümlemesini ve rol atamasını mevcut kimlik sağlayıcınıza (NextAuth, Lucia, Clerk, Auth0, Supabase vb.) devreder.
Kullanıcı yetkilerinizi CopyPatch’in editor ve publisher rollerine eşler.
Veri değiştiren isteklerin güvenlik doğrulamasını ana uygulamanın mantığına bırakır.

lib/copypatch-ozel-auth.ts

import { createCopyPatchBackend } from '@copypatch/backend';
import { type CopyPatchAuthAdapter } from '@copypatch/core';
import { createPostgresPersistence } from '@copypatch/storage-postgres';

// Mevcut kimlik doğrulama sisteminizi (NextAuth, Clerk, Auth0 vb.) bağlayan özel adaptör
interface HostAuthContext {
  user?: {
    id: string;
    isAdmin: boolean;
    canEditCopy: boolean;
    canPublishCopy: boolean;
  };
  csrfValid?: boolean;
}

const hostAuthAdapter: CopyPatchAuthAdapter<HostAuthContext> = {
  async authenticate(_request, context) {
    const user = context.hostAuth?.user;
    if (!user) return null;

    const roles: ('editor' | 'publisher')[] = [];
    if (user.isAdmin || user.canEditCopy) roles.push('editor');
    if (user.isAdmin || user.canPublishCopy) roles.push('publisher');

    return { subject: user.id, roles };
  },

  async verifyMutation(_request, _principal, context) {
    // Ana uygulamanın CSRF belirtecini veya oturum geçerliliğini denetleyin
    return context.hostAuth?.csrfValid === true;
  },
};

const backend = createCopyPatchBackend({
  persistence: createPostgresPersistence({ connectionString: process.env.COPYPATCH_DATABASE_URL! }),
  authAdapter: hostAuthAdapter,
});

3. Kalıcılık (Depolama) Motorları

Adaptör	Sürücü	En Uygun Senaryo	Eşzamanlılık ve İşlemler (Transactions)
`@copypatch/storage-sqlite`	`better-sqlite3`	Tek Node sunucusu, VPS (Hetzner, DigitalOcean), disk bağlı Docker konteyneri.	Senkron SQLite işlemleri, WAL günlük modu, atomik CAS revizyon doğrulaması.
`@copypatch/storage-postgres`	`pg`	Yatayda ölçeklenen çoklu sunucular, Kubernetes, sunucusuz bulut ortamları (Vercel, AWS, Fly.io).	Bağlantı havuzu yönetimi, PostgreSQL advisory transaction kilitleri, sunucular arası hız sınırları.

4. Node Çerçeve Adaptörleri

@copypatch/node paketi, popüler Node.js sunucu çatıları için hafif HTTP köprüleri sağlar:

createNodeHandler(backend) – Yerel Node.js http.createServer
expressMiddleware(backend) – Express ara yazılımı
fastifyCopyPatchHandler(backend) – Fastify rota işleyicisi
createHonoHandler(backend) – Hono Web standart işleyicisi

Geçmiş Sürüm Notu: @copypatch/server v1 sürümündeki bağımsız sunucu süreciydi. v2’de yerini tamamen gömülü çalışan @copypatch/backend ve @copypatch/node kütüphanelerine bırakmıştır. Yayınlanmış eski paketler npm üzerinde kalacaktır; yeni projelerde doğrudan v2 kullanılmalıdır.