From 73a3da42de1136276557e25755fa8e72213c9336 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pere=20Pic=C3=B3?= Date: Wed, 7 Oct 2026 13:49:06 +0200 Subject: [PATCH 1/7] Document SDK design agreements We reached these agreements while working on the async Python SDK and decided they were worth documenting for posterity --- contracts/sdks-performance.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 contracts/sdks-performance.md diff --git a/contracts/sdks-performance.md b/contracts/sdks-performance.md new file mode 100644 index 0000000..a534066 --- /dev/null +++ b/contracts/sdks-performance.md @@ -0,0 +1,26 @@ +# SDK performance assumptions + +This documents specifies a series of design decisions that affect all SDKs across languages. + +## Dropping events is acceptable under load + +Our SDKs let users subscribe to events emitted by the SDK via a callback. +This callback can be too slow, or fail for whatever other reason. +We've reached the decisions that dropping events if the callback cannot keep up is acceptable. + +The bus of events will be lossy, since we've seen that the engineering it takes to make +delivery guarantees + +## Ready is sent at least once and will always be the first event sent + +All SDKs emit a sort of "READY" event. We've decided that we will guarantee at-least-once +delivery, and that the event will signify that the SDK is ready to be used. + +Therefore, it will be the first event that an SDK will emit. + +## SDK makes no guarantees about functionality before initialize is called + +Our SDKs all expect the caller to manage the lifecycle of the SDK with methods +similar to `initialize()` and `stop()`. + +We cannot guarantee that any SDK will work before `initialize()` or after `stop()`. \ No newline at end of file From a1b18fc0e378beff1badefae82b7537a2a4ca2c6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pere=20Pic=C3=B3?= Date: Wed, 7 Oct 2026 14:47:51 +0200 Subject: [PATCH 2/7] Update contracts/sdks-performance.md Co-authored-by: David Leek --- contracts/sdks-performance.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contracts/sdks-performance.md b/contracts/sdks-performance.md index a534066..f55a77b 100644 --- a/contracts/sdks-performance.md +++ b/contracts/sdks-performance.md @@ -9,7 +9,7 @@ This callback can be too slow, or fail for whatever other reason. We've reached the decisions that dropping events if the callback cannot keep up is acceptable. The bus of events will be lossy, since we've seen that the engineering it takes to make -delivery guarantees +delivery guarantees isn't sustainable ## Ready is sent at least once and will always be the first event sent From e97802ec056af93864b00578da019ba301727553 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pere=20Pic=C3=B3?= Date: Wed, 7 Oct 2026 14:54:29 +0200 Subject: [PATCH 3/7] Make language more precise Co-authored-by: Simon Hornby --- contracts/sdks-performance.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contracts/sdks-performance.md b/contracts/sdks-performance.md index f55a77b..2e8eeaa 100644 --- a/contracts/sdks-performance.md +++ b/contracts/sdks-performance.md @@ -14,7 +14,7 @@ delivery guarantees isn't sustainable ## Ready is sent at least once and will always be the first event sent All SDKs emit a sort of "READY" event. We've decided that we will guarantee at-least-once -delivery, and that the event will signify that the SDK is ready to be used. +delivery, and that the event will signify that the SDK has hydrated from at least one of it's API, bootstrap or backup sources. Therefore, it will be the first event that an SDK will emit. From ee06bffc9117907252cee3636e590f84596bdfc1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pere=20Pic=C3=B3?= Date: Wed, 7 Oct 2026 15:03:06 +0200 Subject: [PATCH 4/7] Change language so the decisions apply to all SDKs --- contracts/sdks-performance.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/contracts/sdks-performance.md b/contracts/sdks-performance.md index 2e8eeaa..f4ef952 100644 --- a/contracts/sdks-performance.md +++ b/contracts/sdks-performance.md @@ -1,12 +1,13 @@ -# SDK performance assumptions +# SDK lifecycle design -This documents specifies a series of design decisions that affect all SDKs across languages. +This documents specifies a series of design decisions that affect the lifecycle of SDKs across languages. ## Dropping events is acceptable under load Our SDKs let users subscribe to events emitted by the SDK via a callback. This callback can be too slow, or fail for whatever other reason. -We've reached the decisions that dropping events if the callback cannot keep up is acceptable. +We've reached the decision that it's not acceptable to degrade +the performance of the `is_enabled/get_variant` methods for event handling. The bus of events will be lossy, since we've seen that the engineering it takes to make delivery guarantees isn't sustainable @@ -16,11 +17,10 @@ delivery guarantees isn't sustainable All SDKs emit a sort of "READY" event. We've decided that we will guarantee at-least-once delivery, and that the event will signify that the SDK has hydrated from at least one of it's API, bootstrap or backup sources. -Therefore, it will be the first event that an SDK will emit. - ## SDK makes no guarantees about functionality before initialize is called -Our SDKs all expect the caller to manage the lifecycle of the SDK with methods -similar to `initialize()` and `stop()`. +When an SDK provides an initialize method that is expected to guarantee +the SDK is in a hydrated and functional state, that SDK will not guarantee + proper functioning before that method is called. We cannot guarantee that any SDK will work before `initialize()` or after `stop()`. \ No newline at end of file From 1b483e598474583191c7ea2cc142fe1c183d2212 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pere=20Pic=C3=B3?= Date: Wed, 7 Oct 2026 15:10:04 +0200 Subject: [PATCH 5/7] Remove constraint from the title as well We've agreed that READY being first won't be a thing. It just needs removing from the title, too. --- contracts/sdks-performance.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contracts/sdks-performance.md b/contracts/sdks-performance.md index f4ef952..51e514f 100644 --- a/contracts/sdks-performance.md +++ b/contracts/sdks-performance.md @@ -12,7 +12,7 @@ the performance of the `is_enabled/get_variant` methods for event handling. The bus of events will be lossy, since we've seen that the engineering it takes to make delivery guarantees isn't sustainable -## Ready is sent at least once and will always be the first event sent +## Ready is sent at least once All SDKs emit a sort of "READY" event. We've decided that we will guarantee at-least-once delivery, and that the event will signify that the SDK has hydrated from at least one of it's API, bootstrap or backup sources. From 491672ee74e89d1524d9fbd5c2a4cab4e85d1e4b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pere=20Pic=C3=B3?= Date: Wed, 7 Oct 2026 15:11:48 +0200 Subject: [PATCH 6/7] Apply suggestion from @sighphyre Co-authored-by: Simon Hornby --- contracts/sdks-performance.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/contracts/sdks-performance.md b/contracts/sdks-performance.md index 51e514f..9f061d7 100644 --- a/contracts/sdks-performance.md +++ b/contracts/sdks-performance.md @@ -9,8 +9,7 @@ This callback can be too slow, or fail for whatever other reason. We've reached the decision that it's not acceptable to degrade the performance of the `is_enabled/get_variant` methods for event handling. -The bus of events will be lossy, since we've seen that the engineering it takes to make -delivery guarantees isn't sustainable +The bus of events will be lossy, because of the impact on performance that guaranteeing delivery requires. ## Ready is sent at least once From 32e5cbc935a54690d794212cbf84dcaf8d302d4f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pere=20Pic=C3=B3?= Date: Wed, 7 Oct 2026 15:12:01 +0200 Subject: [PATCH 7/7] Apply suggestion from @sighphyre Co-authored-by: Simon Hornby --- contracts/sdks-performance.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contracts/sdks-performance.md b/contracts/sdks-performance.md index 9f061d7..2478a47 100644 --- a/contracts/sdks-performance.md +++ b/contracts/sdks-performance.md @@ -14,7 +14,7 @@ The bus of events will be lossy, because of the impact on performance that guara ## Ready is sent at least once All SDKs emit a sort of "READY" event. We've decided that we will guarantee at-least-once -delivery, and that the event will signify that the SDK has hydrated from at least one of it's API, bootstrap or backup sources. +delivery, and that the event will signify that the SDK has hydrated from at least one of its API, bootstrap or backup sources. ## SDK makes no guarantees about functionality before initialize is called