diff --git a/.changeset/ruby-flags-explicit-geoip-default.md b/.changeset/ruby-flags-explicit-geoip-default.md new file mode 100644 index 00000000..838da848 --- /dev/null +++ b/.changeset/ruby-flags-explicit-geoip-default.md @@ -0,0 +1,5 @@ +--- +"posthog-ruby": patch +--- + +Explicitly serialize the existing false GeoIP default in remote feature flag requests, while preserving per-call overrides. diff --git a/.github/workflows/sdk-compliance.yml b/.github/workflows/sdk-compliance.yml index f580f539..84669d9f 100644 --- a/.github/workflows/sdk-compliance.yml +++ b/.github/workflows/sdk-compliance.yml @@ -22,11 +22,11 @@ jobs: dockerfile: sdk_compliance_adapter/Dockerfile - mode: sync dockerfile: sdk_compliance_adapter/Dockerfile.sync - uses: PostHog/posthog-sdk-test-harness/.github/workflows/test-sdk-action.yml@75fb00092c6045daef60c30acc10ac83afefbfe9 + uses: PostHog/posthog-sdk-test-harness/.github/workflows/test-sdk-action.yml@dde638562d33572b5c8ac3a2eafc98b92ffa2261 with: adapter-dockerfile: ${{ matrix.dockerfile }} adapter-context: "." - test-harness-version: "1.0.0" + test-harness-version: "1.32.0" report-name: sdk-compliance-ruby-${{ matrix.mode }} sdk-type: server continue-on-error: true diff --git a/lib/posthog/feature_flags.rb b/lib/posthog/feature_flags.rb index 555cf05a..64475061 100644 --- a/lib/posthog/feature_flags.rb +++ b/lib/posthog/feature_flags.rb @@ -203,7 +203,8 @@ def get_flags(distinct_id, groups = {}, person_properties = {}, group_properties group_properties: group_properties } request_data[:flag_keys_to_evaluate] = flag_keys if flag_keys && !flag_keys.empty? - request_data[:geoip_disable] = disable_geoip unless disable_geoip.nil? + # The flags endpoint treats an omitted/null value as false; serialize that same default explicitly. + request_data[:geoip_disable] = disable_geoip.nil? ? false : disable_geoip flags_response = _request_feature_flag_evaluation(request_data) diff --git a/sdk_compliance_adapter/README.md b/sdk_compliance_adapter/README.md index 060ba2a2..db463020 100644 --- a/sdk_compliance_adapter/README.md +++ b/sdk_compliance_adapter/README.md @@ -11,43 +11,55 @@ An explicit UUID is forwarded to `capture`. Timestamp strings are parsed into `Time` objects; UTC conversion and serialization remain SDK-owned. Compression uses the SDK's gzip default unless `enable_compression` is supplied at init. +For sync `/capture`, HTTP 200 and `success: true` mean the native invocation +completed, not that delivery succeeded. `delivered` preserves the SDK's boolean +return value, including false after a terminal response or exhausted retries. +Errors remain visible in `/state` and mock traffic; raised exceptions still +produce HTTP 500. Async capture continues to acknowledge queue acceptance and +does not return `delivered`. + Flags use `evaluate_flags(..., flag_keys: [key]).get_flag(key)`, not the deprecated `get_feature_flag` API. The SDK owns response parsing, retries and the real `$feature_flag_called` event. No local-evaluation secret is configured, so the -remote profile evaluates on each action. Omitted `disable_geoip` remains omitted; -explicit values are forwarded. +remote profile evaluates on each action. Omitted `disable_geoip` remains omitted +when calling the SDK; explicit values are forwarded. The native SDK serializes +omitted/nil as `geoip_disable: false`, preserving the flags endpoint's existing +effective default rather than changing GeoIP lookup behavior. ## Inventory and interpretation -CI uses harness **1.0.0**, server wire format, sequential execution, and separate -async/sync artifacts. Each profile selects the unchanged **47** definitions: +CI uses published harness **1.32.0**, server wire format, sequential execution, and separate +async/sync artifacts. Each profile selects **47** definitions: 30 V0 capture and 17 feature flags. Assertion failures remain advisory; a separate inventory check requires both complete reports. V1, dedicated AI and non-gzip codecs are unsupported and are not advertised. -Local harness 1.0.0 results with Ruby 3.4.7 and SDK 3.23.6: - -| Profile | Selected | Passed | Failed | -| --- | ---: | ---: | ---: | -| async | 47 | 46 | 1 | -| sync | 47 | 45 | 2 | +The adapter declares `synchronous_capture` only for sync mode. Published harness +1.32.0 uses that capability to check five distinct events delivered immediately +in five requests, one event per request, with unique UUIDs and no extra request +on flush under +`capture.batch_format.synchronous_capture_delivers_each_event_immediately`. +Async retains `capture.batch_format.multiple_events_batched_together`. +The published harness selects between these cases using `synchronous_capture`; +the SDK workflow adds no filtering. The batch retry case inspects a retried +single-event request in sync mode, not multi-event batching. -Both profiles expose -`feature_flags.request_payload.disable_geoip_omitted_defaults_to_false`: the -native SDK omits `geoip_disable`, while this definition requires literal false. -Explicit false propagation passes. The adapter does not override this default. +Sync retry/error cases inspect wire traffic even when native capture returns +false for unsuccessful delivery. The adapter does not change SDK retry or +delivery behavior. -Sync additionally fails `capture.batch_format.multiple_events_batched_together` -(five requests rather than one). Sync does not accumulate a multi-event batch, -so this definition and -`capture.deduplication.preserves_uuid_and_timestamp_on_batch_retry` are not -multi-event batching coverage for that profile. The latter passes by inspecting -a retried single-event request. Both definitions still execute without filtering; -the other 28 capture definitions exercise supported synchronous behavior. +Native flags serialization explicitly carries the effective value required by the +canonical [GeoIP contract](https://github.com/PostHog/sdk-specs/blob/53e9bc16d14f973809f80049864866d5b6d9bdff/openspec/specs/capture/spec.md#requirement-client-level-geoip-control-with-per-call-override). +The [flags endpoint](https://github.com/PostHog/posthog/blob/ba1d628545b337816ba39df67e59726f099159c8/rust/feature-flags/src/handler/properties.rs#L20) +already treats omitted/null as false. No public signature or effective privacy +default changed, and the adapter does not supply a default option. -The new UTC override case and SDK-generated UUID presence/uniqueness definitions -pass in both profiles. These results certify neither every Ruby version nor the -Docker runtime until CI runs. +The reusable workflow is pinned to release commit +`dde638562d33572b5c8ac3a2eafc98b92ffa2261`, whose release inputs pin specs commit +`53e9bc16d14f973809f80049864866d5b6d9bdff`. The published V1 image digest is +`sha256:7eb6c62e2241ddd48a2dfb326652e7933cd2fe26e0ffcad98cd385d603b4eb82`. +Actual async and sync reports must each show 47/47 passing to establish compliance; +a green advisory job or inventory check alone does not prove this. `/state` retains diagnostic limitations: transport observation covers capture requests, not flags HTTP retries; capture counts exclude automatic flag-access @@ -68,4 +80,4 @@ SDK_MODE=sync docker compose -f sdk_compliance_adapter/docker-compose.yml up --b For a native launch, unset `STUB` (it disables SDK HTTP), set `RUBYLIB=lib`, and run `ruby sdk_compliance_adapter/adapter.rb` with the desired `PORT` and -`SDK_MODE`. Point harness 1.0.0 at that listener and an available local mock port. +`SDK_MODE`. Point harness 1.32.0 at that listener and an available local mock port. diff --git a/sdk_compliance_adapter/adapter.rb b/sdk_compliance_adapter/adapter.rb index 12bcb6c5..a68070dd 100644 --- a/sdk_compliance_adapter/adapter.rb +++ b/sdk_compliance_adapter/adapter.rb @@ -243,7 +243,7 @@ def health sdk_name: "posthog-ruby-#{@mode}", sdk_version: PostHog::VERSION, adapter_version: '1.0.0', - capabilities: %w[capture_v0 encoding_gzip] + capabilities: %w[capture_v0 encoding_gzip] + (@mode == 'sync' ? ['synchronous_capture'] : []) } ] end @@ -295,9 +295,14 @@ def capture(data) attrs[:timestamp] = Time.iso8601(data['timestamp']) if data['timestamp'] Thread.current[:sdk_compliance_uuid] = nil - if client.capture(attrs) + captured = client.capture(attrs) + if @mode == 'sync' || captured SDKComplianceAdapter.state.increment_captured(pending: @mode != 'sync') - [200, { success: true, uuid: Thread.current[:sdk_compliance_uuid] }] + # Sync capture returns delivery status, not queue acceptance. A completed invocation + # lets the harness inspect transport failures; do not present it as successful delivery. + result = { success: true, uuid: Thread.current[:sdk_compliance_uuid] } + result[:delivered] = captured if @mode == 'sync' + [200, result] else [500, { error: 'capture was not queued' }] end diff --git a/sdk_compliance_adapter/docker-compose.yml b/sdk_compliance_adapter/docker-compose.yml index f6cb20ca..1fabbf86 100644 --- a/sdk_compliance_adapter/docker-compose.yml +++ b/sdk_compliance_adapter/docker-compose.yml @@ -9,7 +9,7 @@ services: - test-network test-harness: - image: ghcr.io/posthog/sdk-test-harness:1.0.0 + image: ghcr.io/posthog/sdk-test-harness:1.32.0 command: ["run", "--adapter-url", "http://sdk-adapter:8080", "--mock-url", "http://test-harness:8081"] networks: - test-network diff --git a/spec/posthog/client_spec.rb b/spec/posthog/client_spec.rb index 9d734444..b55bacd2 100644 --- a/spec/posthog/client_spec.rb +++ b/spec/posthog/client_spec.rb @@ -2079,7 +2079,7 @@ def release 'company' => { '$group_key' => 'id:5', 'x' => 'y' }, 'instance' => { '$group_key' => 'app.posthog.com' } }, - 'person_properties' => { 'x1' => 'y1' }, 'token' => 'testsecret' + 'person_properties' => { 'x1' => 'y1' }, 'geoip_disable' => false, 'token' => 'testsecret' } ) @@ -2103,7 +2103,7 @@ def release 'instance' => { '$group_key' => 'app.posthog.com' } }, 'person_properties' => { 'distinct_id' => 'override' }, - 'token' => 'testsecret' + 'geoip_disable' => false, 'token' => 'testsecret' } ) WebMock.reset_executed_requests! @@ -2113,7 +2113,7 @@ def release assert_requested :post, flags_endpoint, times: 1 expect(WebMock).to have_requested(:post, flags_endpoint).with( body: { 'distinct_id' => 'some_id', 'groups' => {}, 'group_properties' => {}, - 'person_properties' => {}, 'token' => 'testsecret' } + 'person_properties' => {}, 'geoip_disable' => false, 'token' => 'testsecret' } ) WebMock.reset_executed_requests! @@ -2125,7 +2125,7 @@ def release 'groups' => { 'company' => 'id:5' }, 'group_properties' => { 'company' => { '$group_key' => 'id:5' } }, 'person_properties' => {}, - 'token' => 'testsecret' + 'geoip_disable' => false, 'token' => 'testsecret' } ) WebMock.reset_executed_requests! @@ -2140,7 +2140,7 @@ def release assert_requested :post, flags_endpoint, times: 1 expect(WebMock).to have_requested(:post, flags_endpoint).with( body: { 'distinct_id' => 'some_id', 'groups' => {}, 'group_properties' => {}, - 'person_properties' => {}, 'token' => 'testsecret' } + 'person_properties' => {}, 'geoip_disable' => false, 'token' => 'testsecret' } ) WebMock.reset_executed_requests! @@ -2148,7 +2148,7 @@ def release assert_requested :post, flags_endpoint, times: 1 expect(WebMock).to have_requested(:post, flags_endpoint).with( body: { 'distinct_id' => 'some_id', 'groups' => {}, 'group_properties' => {}, - 'person_properties' => {}, 'token' => 'testsecret' } + 'person_properties' => {}, 'geoip_disable' => false, 'token' => 'testsecret' } ) WebMock.reset_executed_requests! end diff --git a/spec/posthog/feature_flag_evaluations_spec.rb b/spec/posthog/feature_flag_evaluations_spec.rb index d9895e6d..2698881b 100644 --- a/spec/posthog/feature_flag_evaluations_spec.rb +++ b/spec/posthog/feature_flag_evaluations_spec.rb @@ -674,12 +674,15 @@ def capture_stderr end describe 'disable_geoip' do - it 'forwards disable_geoip: as geoip_disable in the /flags request body' do - stub_flags(flags_response) - client.evaluate_flags('user-1', disable_geoip: true) - expect(WebMock).to have_requested(:post, FLAGS_ENDPOINT).with( - body: hash_including(geoip_disable: true) - ) + { 'omitted' => {}, 'nil' => { disable_geoip: nil }, 'false' => { disable_geoip: false }, + 'true' => { disable_geoip: true } }.each do |input, options| + it "serializes #{input} GeoIP input with the existing effective backend default" do + stub_flags(flags_response) + client.evaluate_flags('user-1', **options) + expect(WebMock).to have_requested(:post, FLAGS_ENDPOINT).with( + body: hash_including(geoip_disable: options[:disable_geoip] == true) + ) + end end end diff --git a/spec/posthog/feature_flag_spec.rb b/spec/posthog/feature_flag_spec.rb index a9b5986e..71849220 100644 --- a/spec/posthog/feature_flag_spec.rb +++ b/spec/posthog/feature_flag_spec.rb @@ -429,7 +429,7 @@ module PostHog 'group_properties' => {}, 'person_properties' => { 'region' => 'USA', 'email' => 'a@b.com' }, - 'token' => 'testsecret' + 'geoip_disable' => false, 'token' => 'testsecret' } ) @@ -446,7 +446,7 @@ module PostHog 'groups' => {}, 'group_properties' => {}, 'person_properties' => { 'doesnt_matter' => '1' }, - 'token' => 'testsecret' + 'geoip_disable' => false, 'token' => 'testsecret' } ) @@ -5185,7 +5185,7 @@ module PostHog # Add the exact stub for the `/flags` endpoint as recommended in the error stub_request(:post, 'https://us.i.posthog.com/flags/?v=2').with( - body: '{"distinct_id":"distinct_id","groups":{},"person_properties":{"region":"USA"},"group_properties":{},"token":"testsecret"}', # rubocop:disable Layout/LineLength + body: '{"distinct_id":"distinct_id","groups":{},"person_properties":{"region":"USA"},"group_properties":{},"geoip_disable":false,"token":"testsecret"}', # rubocop:disable Layout/LineLength headers: { 'Accept' => '*/*', 'Accept-Encoding' => 'gzip;q=1.0,deflate;q=0.6,identity;q=0.3', diff --git a/spec/sdk_compliance_adapter_spec.rb b/spec/sdk_compliance_adapter_spec.rb index d6433810..c27f6f16 100644 --- a/spec/sdk_compliance_adapter_spec.rb +++ b/spec/sdk_compliance_adapter_spec.rb @@ -32,7 +32,11 @@ def request(server, path, data = {}) end it 'identifies the profile without changing SDK wire attribution' do - expect(server.send(:health).last[:sdk_name]).to eq("posthog-ruby-#{mode}") + health = server.send(:health).last + expect(health[:sdk_name]).to eq("posthog-ruby-#{mode}") + expect(health[:capabilities]).to eq( + %w[capture_v0 encoding_gzip] + (mode == 'sync' ? ['synchronous_capture'] : []) + ) request(server, '/capture', distinct_id: 'user', event: 'example') request(server, '/flush') expect(batches.first['batch'].first['properties']['$lib']).to eq('posthog-ruby') @@ -51,6 +55,26 @@ def request(server, path, data = {}) expect(SDKComplianceAdapter.state.snapshot).to include(total_events_captured: 1, pending_events: 0) end + it 'distinguishes completed invocation from synchronous delivery' do + status, result = request(server, '/capture', distinct_id: 'user', event: 'example') + expect(status).to eq(200) + expect(result[:success]).to be(true) + if mode == 'sync' + expect(result[:delivered]).to be(true) + else + expect(result).not_to have_key(:delivered) + end + end + + it 'preserves capture exceptions as adapter errors' do + allow(SDKComplianceAdapter.state.client).to receive(:capture).and_raise('unexpected capture failure') + expect(request(server, '/capture', distinct_id: 'user', event: 'example')) + .to eq([500, { error: 'unexpected capture failure' }]) + expect(SDKComplianceAdapter.state.snapshot).to include( + total_events_captured: 0, last_error: 'unexpected capture failure' + ) + end + it 'generates distinct UUIDs across captures and forwards a supplied UUID unchanged' do results = 2.times.map { request(server, '/capture', distinct_id: 'user', event: 'example').last } uuid = '12345678-1234-4567-890a-123456789abc' @@ -92,13 +116,16 @@ def request(server, path, data = {}) end data = { key: 'example', distinct_id: 'user' } data[:disable_geoip] = disable_geoip unless disable_geoip.nil? + options = { + groups: {}, person_properties: {}, group_properties: {}, only_evaluate_locally: false, + flag_keys: ['example'] + } + options[:disable_geoip] = disable_geoip unless disable_geoip.nil? + expect(SDKComplianceAdapter.state.client).to receive(:evaluate_flags) + .with('user', **options).and_call_original expect(request(server, '/get_feature_flag', data)).to eq([200, { success: true, value: 'variant' }]) expect(flag_requests.first['flag_keys_to_evaluate']).to eq(['example']) - if disable_geoip.nil? - expect(flag_requests.first).not_to have_key('geoip_disable') - else - expect(flag_requests.first['geoip_disable']).to eq(disable_geoip) - end + expect(flag_requests.first['geoip_disable']).to eq(disable_geoip == true) expect(batches.flat_map { |batch| batch['batch'].map { |event| event['event'] } }) .to eq(['$feature_flag_called']) end @@ -106,6 +133,57 @@ def request(server, path, data = {}) end end + it 'does not reinterpret an async enqueue failure as a completed capture' do + server = described_class.new(mode: 'async') + request(server, '/init', api_key: 'test-key', host: host) + allow(SDKComplianceAdapter.state.client).to receive(:capture).and_return(false) + expect(request(server, '/capture', distinct_id: 'user', event: 'example')) + .to eq([500, { error: 'capture was not queued' }]) + expect(SDKComplianceAdapter.state.snapshot[:total_events_captured]).to eq(0) + end + + context 'with synchronous delivery failures' do + let(:server) { described_class.new(mode: 'sync') } + + [400, 401, 403, 413, 503].each do |status_code| + it "acknowledges invocation without claiming delivery after HTTP #{status_code}" do + request(server, '/init', api_key: 'test-key', host: host, max_retries: 0) + stub_request(:post, "#{host}/batch/").to_return( + status: status_code, body: JSON.generate(error: 'delivery failed') + ) + + status, result = request(server, '/capture', distinct_id: 'user', event: 'example') + expect(status).to eq(200) + expect(result).to include(success: true, delivered: false) + expect(result[:uuid]).to match(/\A[0-9a-f-]{36}\z/) + expect(SDKComplianceAdapter.state.snapshot).to include( + total_events_captured: 1, total_events_sent: 0, pending_events: 0, + last_error: 'delivery failed', requests_made: [include(status_code: status_code, retry_attempt: 0)] + ) + expect(a_request(:post, "#{host}/batch/")).to have_been_made.once + end + end + + it 'preserves the native retry budget before acknowledging failed delivery' do + request(server, '/init', api_key: 'test-key', host: host, max_retries: 2) + stub_request(:post, "#{host}/batch/").to_return(status: 503, body: '{"error":"unavailable"}') + + expect(request(server, '/capture', distinct_id: 'user', event: 'example').last) + .to include(success: true, delivered: false) + expect(SDKComplianceAdapter.state.snapshot).to include( + total_retries: 2, total_events_sent: 0, last_error: 'unavailable' + ) + expect(a_request(:post, "#{host}/batch/")).to have_been_made.times(3) + end + + it 'sends each event immediately rather than emulating queued batching' do + request(server, '/init', api_key: 'test-key', host: host, flush_at: 100, flush_interval_ms: 60_000) + 2.times { request(server, '/capture', distinct_id: 'user', event: 'example') } + expect(batches.map { |batch| batch['batch'].length }).to eq([1, 1]) + expect(request(server, '/flush').last[:events_flushed]).to eq(0) + end + end + it 'rejects an unknown profile' do expect { described_class.new(mode: 'unknown') }.to raise_error(ArgumentError, 'SDK_MODE must be async or sync') end