Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/ruby-flags-explicit-geoip-default.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"posthog-ruby": patch
---

Explicitly serialize the existing false GeoIP default in remote feature flag requests, while preserving per-call overrides.
4 changes: 2 additions & 2 deletions .github/workflows/sdk-compliance.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 2 additions & 1 deletion lib/posthog/feature_flags.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
62 changes: 37 additions & 25 deletions sdk_compliance_adapter/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
11 changes: 8 additions & 3 deletions sdk_compliance_adapter/adapter.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion sdk_compliance_adapter/docker-compose.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
12 changes: 6 additions & 6 deletions spec/posthog/client_spec.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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'
}
)

Expand All @@ -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!
Expand All @@ -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!

Expand All @@ -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!
Expand All @@ -2140,15 +2140,15 @@ 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!

client.is_feature_enabled('random_key', 'some_id', groups: {}, person_properties: nil, group_properties: nil)
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
Expand Down
15 changes: 9 additions & 6 deletions spec/posthog/feature_flag_evaluations_spec.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
6 changes: 3 additions & 3 deletions spec/posthog/feature_flag_spec.rb
Original file line number Diff line number Diff line change
Expand Up @@ -429,7 +429,7 @@ module PostHog
'group_properties' => {},
'person_properties' => { 'region' => 'USA',
'email' => 'a@b.com' },
'token' => 'testsecret'
'geoip_disable' => false, 'token' => 'testsecret'
}
)

Expand All @@ -446,7 +446,7 @@ module PostHog
'groups' => {},
'group_properties' => {},
'person_properties' => { 'doesnt_matter' => '1' },
'token' => 'testsecret'
'geoip_disable' => false, 'token' => 'testsecret'
}
)

Expand Down Expand Up @@ -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',
Expand Down
90 changes: 84 additions & 6 deletions spec/sdk_compliance_adapter_spec.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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')
Expand All @@ -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'
Expand Down Expand Up @@ -92,20 +116,74 @@ 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
end
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
Expand Down
Loading