swift-kurrentdb

Typed errors for deleted streams and conflicts, and KurrentDB 26.2刪除的 stream 與版本衝突改成型別化錯誤，並支援 KurrentDB 26.2

2.6 turns server errors that used to surface as raw gRPC errors into typed KurrentErrors, adds KurrentDB 26.2 to the tested servers, and documents the source and license of every bundled .proto file. The public API is source compatible with 2.5; read the upgrade notes if you match errors from delete, tombstone or a buffered read().

2.6 把原本以原始 gRPC 錯誤冒出來的伺服器錯誤，改成型別化的 KurrentError； 測試的伺服器加入 KurrentDB 26.2；並記錄每個內附 .proto 檔的來源與授權。 公開 API 與 2.5 原始碼相容；如果你有比對 delete、tombstone 或一般 read() 丟出的錯誤，請先看下面的升級注意事項。

Typed errors型別化錯誤

A read() the server rejects now throws the same KurrentError as read().lazy: resourceDeleted for a tombstoned stream, accessDenied without permission. delete and tombstone report a revision conflict as wrongExpectedVersion(expected:current:), the same case append throws, with current set to .noStream when the stream does not exist.

被伺服器拒絕的 read()，現在會丟出跟 read().lazy 一樣的 KurrentError：stream 被 tombstone 時是 resourceDeleted，沒有權限時是 accessDenied。delete 和 tombstone 遇到版本衝突時，改丟 wrongExpectedVersion(expected:current:)，跟 append 同一個 case；stream 不存在時 current 是 .noStream。

do {
    try await client.streams(specified: "orders").delete {
        $0.expectedRevision = .at(3)
    }
} catch KurrentError.wrongExpectedVersion(_, let current) {
    // current is .noStream or .revision(n)
}

KurrentDB 26.2KurrentDB 26.2

CI now tests KurrentDB 26.2 across Swift 6.0–6.4, on a single TLS node: 26.2 needs a Kurrent license to run a multi-node cluster. X.509 user certificates are tested on every run against an unlicensed 26.2 node. 26.2 rejects creating transient projections as deprecated.

CI 現在在 Swift 6.0–6.4 上測試 KurrentDB 26.2，使用單一 TLS 節點，因為 26.2 的多節點 cluster 需要 Kurrent license。X.509 使用者憑證每次都會對一個沒有 license 的 26.2 節點測試。26.2 會以 deprecated 為由拒絕建立 transient projection。

More changes其他變更

• KurrentError.CurrentRevisionOption is renamed CurrentRevisionState, because it is the server's observed state, not an option. The old name remains as a deprecated typealias.
• KurrentError.CurrentRevisionOption 改名為 CurrentRevisionState，因為它是伺服器觀察到的狀態，不是呼叫端的選項。舊名稱保留為 deprecated typealias。
• The license file is now LICENSE, and a new NOTICE records the source and license of every bundled .proto file. The unused schema registry protos, the only ones under the Kurrent License v1, are removed; they were package-level only.
• 授權檔改名為 LICENSE，新增的 NOTICE 記錄每個內附 .proto 檔的來源與授權。沒用到的 schema registry protos（唯一採用 Kurrent License v1 的檔案）已移除；它們只有 package 層級，不影響公開 API。

Upgrade notes升級注意事項

• Code that matched KurrentError.grpcError for a delete or tombstone revision conflict now receives wrongExpectedVersion.
• 原本用 KurrentError.grpcError 比對 delete 或 tombstone 版本衝突的程式，現在會收到 wrongExpectedVersion。
• A buffered read() the server rejects throws resourceDeleted or accessDenied instead of a raw RPCError, still while iterating. Errors after the server accepted the call are unchanged.
• 被伺服器拒絕的一般 read()，改丟 resourceDeleted 或 accessDenied，不再是原始的 RPCError；一樣是在迭代時丟出。伺服器接受呼叫之後發生的錯誤不變。

Full 2.6.0 release notes →2.6.0 完整 release notes →

Reads that stream, and inputs that can't hurt you邊讀邊用的讀取，以及傷不了你的輸入

2.5 lets a read hand you events as you iterate instead of loading the whole result first, puts a bound on subscription memory, and closes every finding of a security review — connection strings, credentials, CA certificates and server responses can no longer crash the process, leak a password, or quietly weaken TLS. The public API is source compatible with 2.4, but some inputs 2.4 accepted now throw: read the upgrade notes below.

2.5 讓讀取可以邊迭代邊交出事件，不必先把整批結果載入；訂閱的記憶體也有了上限。 同時處理完一次安全盤點的所有項目 —— 連線字串、帳密、CA 憑證和伺服器回應，都不會再讓程序崩潰、 洩漏密碼，或悄悄降低 TLS 的保護。公開 API 與 2.4 原始碼相容，但有些 2.4 接受的輸入現在會報錯： 升級前請先看下面的升級注意事項。

Lazy reads and bounded subscriptionsLazy 讀取與有上限的訂閱

read().lazy pulls events from the server as your loop consumes them, and the call ends as soon as the loop does — on completion, break, a thrown error or cancellation. Plain read() keeps the 2.4 behaviour (the whole result first). Subscriptions now wait for your code instead of piling events up in memory.

read().lazy 會隨著你的迴圈消費，才向伺服器拉下一筆事件；迴圈一結束（跑完、break、丟錯或取消），這次呼叫就跟著結束。一般的 read() 維持 2.4 的行為（先拿完整批結果）。訂閱現在會等你的程式消費，不會把事件一直堆在記憶體裡。

for try await response in client.streams(specified: "orders").read().lazy {
    // events arrive as you iterate; memory does not grow with the stream
}

Strict connection strings嚴格的連線字串

Connection strings are parsed according to RFC 3986. A character in your password can no longer turn off TLS or point the client at another host; unknown, duplicate or invalid parameters throw instead of being ignored; and error messages name the parameter, never its value. Percent-encode a password that contains @ / ? # % — or pass it with .authenticated(.credentials(username:password:)) and skip the connection string.

連線字串改成依照 RFC 3986 解析。密碼裡的字元再也不能關掉 TLS，或讓 client 連到別的 host；未知、重複或格式錯誤的參數會直接報錯，不會被默默忽略；錯誤訊息只寫參數名稱，不會帶出值。密碼含 @ / ? # % 時請先 percent-encode，或改用 .authenticated(.credentials(username:password:))，完全不經過連線字串。

More fixes其他修正

• defaultDeadline now takes effect for calls that complete before they return (appends, deletes, management calls, read()); subscriptions and read().lazy are not bounded by it.
• defaultDeadline 現在真的會生效，套用在回傳前就完成的呼叫（append、delete、管理類呼叫、read()）；訂閱和 read().lazy 不受它限制。
• A CA certificate that can't be read is reported instead of silently trusting the system's root certificates. Use certificate(path:fallback:); certificate(path:) is deprecated.
• CA 憑證讀不到時會直接報錯，不再悄悄改成信任系統的根憑證。請改用 certificate(path:fallback:)；certificate(path:) 已標成 deprecated。
• Negative revisions or positions from the server and credentials that can't be encoded fail with an error instead of crashing the process or sending the request anonymously.
• 伺服器回傳負數 revision 或 position、帳密無法編碼時，會回傳錯誤，不再讓程序崩潰，也不會不帶認證就把請求送出去。

Upgrade notes升級注意事項

• Connection strings with unknown parameters (including other clients' parameters such as throwOnAppendFailure), malformed values, or unencoded @ in a value (write %40) now throw.
• 連線字串裡有未知參數（包括其他 client 才有的參數，例如 throwOnAppendFailure）、格式錯誤的值，或參數值裡有沒編碼的 @（要寫成 %40），現在都會報錯。
• Connection strings without gossipTimeout now use 3 seconds, like settings built in code (it was 5).
• 沒有寫 gossipTimeout 的連線字串，現在預設 3 秒，跟用程式建立的設定一致（以前是 5 秒）。
• If you set defaultDeadline, calls that run longer now fail with deadlineExceeded.
• 如果你有設定 defaultDeadline，超過時間的呼叫現在會以 deadlineExceeded 失敗。
• An unreadable tlsCaFile makes parse throw; an unreadable file given to certificate(path:) makes the client refuse to connect.
• tlsCaFile 讀不到時 parse 會報錯；交給 certificate(path:) 的檔案讀不到時，client 會拒絕連線。

Full 2.5.0 release notes →2.5.0 完整 release notes →

Connection reuse — faster and more solid連線復用 —— 更快，也更穩

Up to 2.3, every single call — each append, each read, each delete — dialled a brand-new connection to the server: a TCP handshake, a TLS handshake, the request, then hang up. 2.4 keeps the line open. Same API, nothing to change in your code; it just gets faster and holds up better.

到 2.3 為止，每一次呼叫（每個 append、每個 read、每個 delete）都會跟伺服器重新「撥一通電話」： TCP 握手、TLS 握手、講一句話，然後掛掉。2.4 開始，線路會一直保持接通。API 完全一樣， 你的程式碼一行都不用改，就是變快、也變穩了。

The life of a shared connection一條共用連線的一生

1. Opened建立on the first call to that node第一次打到這個 node 時
2. In use使用中any number of calls share it多少個呼叫都一起用
3. Idle閒置no calls in flight目前沒有呼叫在跑
4. Retired回收after 1 hour idle閒置超過 1 小時
5. Reopened重新建立on the next call, automatically下次呼叫時自動重開

A connection is never retired while a call is using it — the client keeps count.

只要還有呼叫在用，連線就不會被回收 —— client 會記著目前有幾個人在用。

What you need to do你需要做什麼

Almost nothing. Create one client for your whole app and share it — creating a new client per request means connections can't be shared.

幾乎什麼都不用做。整個 app 建一個 client、到處共用就好 —— 如果每個請求都 new 一個 client，連線就沒辦法共用了。

// One client for the whole app
let client = KurrentDBClient(settings: settings)

// When the app is shutting down
try client.shutdown()

2.4.1: dropped subscriptions hang up2.4.1：訂閱丟掉就掛線

A persistent subscription's connection now closes as soon as nothing references the subscription or its events stream — even if you never iterated it. Before 2.4.1 a retain cycle kept those connections open.

只要沒有人再持有持久訂閱或它的 events stream，它的連線就會關閉 —— 就算從來沒迭代過也一樣。2.4.1 之前，一個 retain cycle 會讓這些連線一直開著。

2.4.2: retries that actually wait, and X.509 that actually sends2.4.2：重試真的會等，X.509 真的會送

• Settings built in code (.localhost(), .remote(), ClientSettings(...)) waited 100 µs between node-discovery retries instead of 100 ms, so a leader election failed calls at once. They now wait 100 ms, like connection strings.
• 用程式建立的設定（.localhost()、.remote()、ClientSettings(...)）在節點探索重試之間只等 100 µs 而不是 100 ms，所以換 leader 時呼叫會直接失敗。現在跟連線字串一樣等 100 ms。
• userCertFile / userKeyFile now present the client certificate in the TLS handshake; before, the connection was silently anonymous.
• userCertFile / userKeyFile 現在會在 TLS 握手時出示用戶端憑證；以前連線會悄悄變成匿名。
• Every Swift example in the docs is now compiled in CI.
• 文件裡的每個 Swift 範例現在都會在 CI 編譯檢查。

2.4.3: reads share the connection2.4.3：讀取共用連線

• read(), readAll(), projection statistics and user details now use the per-node shared connection instead of opening a TCP connection for every call. Only subscriptions, persistent subscriptions and server statistics keep a dedicated one.
• read()、readAll()、projection statistics 與 user details 現在走每個節點的共用連線，不再每次呼叫都開一條 TCP 連線。只有訂閱、persistent subscription 與 server statistics 維持獨立連線。
• A burst of reads beyond the server's concurrent-stream limit queues on the shared connection alongside appends instead of opening more sockets.
• 超過伺服器並行 stream 上限的讀取會在共用連線上跟 append 一起排隊，不再多開 socket。

Full 2.4.3 release notes →2.4.3 完整 release notes →

Full 2.4.2 release notes →2.4.2 完整 release notes →

Full 2.4.0 release notes →2.4.0 完整 release notes →

Test isolation and endpoint resolution測試隔離與 endpoint 解析

2.3 adds a pool for running tests against several independent KurrentDB instances, and fixes how a selected node's address is resolved.

2.3 新增了一個 pool，讓測試可以同時跑在多個彼此獨立的 KurrentDB instance 上，並修正了選中 node 的位址解析方式。

Full 2.3.0 release notes →2.3.0 完整 release notes →

Settings from the environment從環境變數建立設定

2.2 makes it easy to keep connection details out of your source code, and fixes reading metadata from a stream that has none yet.

2.2 讓連線資訊更容易留在程式碼之外，並修正了讀取尚無 metadata 的 stream 時的行為。

let settings = try ClientSettings.fromEnv()
let custom = try ClientSettings.fromEnv(key: "MY_KURRENTDB_URL")

Full 2.2.0 release notes →2.2.0 完整 release notes →

New write and read capabilities新的寫入與讀取能力

2.1 builds on the 2.0 target-based API with new write and read capabilities, per-call authentication, and a hardened persistent-subscription connection lifecycle.

2.1 在 2.0 的 target-based API 上，新增寫入與讀取能力、逐請求認證，並強化了持久訂閱的連線生命週期。

Full 2.1.0 release notes →2.1.0 完整 release notes →

A ground-up redesign of the APIAPI 全面重新設計

Version 2.0 is a ground-up redesign of the public API. The flat client.appendToStream(...) surface gives way to typed targets the compiler can verify — illegal operations literally don't compile.

2.0 是 API 的全面重新設計。原本 client.appendToStream(...) 的扁平呼叫， 換成編譯器能驗證的型別化 target —— 不合法的操作根本通不過編譯。

See the difference前後對照

// Append
try await client.appendToStream(
    "orders",
    events: [event]
) {
    $0.revision(expected: .streamExists)
}

// Read
let responses = try await client.readStream("orders") {
    $0.startFrom(revision: .start).limit(50)
}

// Persistent subscription
try await client.createPersistentSubscription(
    stream: "orders",
    groupName: "workers"
) {
    $0.startFrom(revision: .start)
      .maxRetryCount(5)
}

// Append
try await client.streams(specified: "orders")
    .append(events: [event]) {
        $0.expectedRevision = .streamExists
    }

// Read
let responses = try await client.streams(specified: "orders").read {
    $0.revision = .start
    $0.limit = 50
}

// Persistent subscription
try await client.persistentSubscriptions(
    stream: "orders", group: "workers"
).create {
    $0.revision = .start
    $0.settings.maxRetryCount = 5
}

Full 2.0.0 release notes →2.0.0 完整 release notes →