feralin 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +7 -0
- data/CHANGELOG.md +9 -0
- data/LICENSE +21 -0
- data/README.md +152 -0
- data/lib/feralin/client.rb +582 -0
- data/lib/feralin/error_event.rb +141 -0
- data/lib/feralin/errors.rb +32 -0
- data/lib/feralin/events.rb +226 -0
- data/lib/feralin/profile.rb +77 -0
- data/lib/feralin/rack.rb +159 -0
- data/lib/feralin/railtie.rb +59 -0
- data/lib/feralin/revenue.rb +81 -0
- data/lib/feralin/transport.rb +59 -0
- data/lib/feralin/ulid.rb +75 -0
- data/lib/feralin/version.rb +5 -0
- data/lib/feralin.rb +19 -0
- metadata +64 -0
checksums.yaml
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
---
|
|
2
|
+
SHA256:
|
|
3
|
+
metadata.gz: dee494448fa406a1ea3043f2a7cd3f41ce05a020587c5eae5aaa84c2a5e770e5
|
|
4
|
+
data.tar.gz: 42708fe238a135a87451671dd1c7b0d936c22b4da4d5fcbfe7bda63c56449e41
|
|
5
|
+
SHA512:
|
|
6
|
+
metadata.gz: 5a742f4009967b55e0a9e6a50f658fe9ebb95dfca408be8e0a4df9dc91b0e297200bcac44e90575c0a802f9cfdeb2a6e4176527c0b58f3b919d2bc09149ab6df
|
|
7
|
+
data.tar.gz: f0449aca1534c23d058d991a550980a67732bff6bb4f9a2ece0c9123361cba65f45e541f2c639a6a7f20263c4ad5708aeec832f47292066fd51145468ef93ddd
|
data/CHANGELOG.md
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# Değişiklikler
|
|
2
|
+
|
|
3
|
+
## Yayınlanmamış
|
|
4
|
+
|
|
5
|
+
- `track_revenue` → `feralin_purchase`, `group` → `fr_group`, `set_user_properties` → `fr_user_properties`, `capture_error` → `fr_error` (Android SDK ile aynı gövde, ham backtrace yok, 60 sn'de 20 olay, parmak izi başına 3); `app_version:` ve `error_sample_rate:` seçenekleri; Rack `Tracker` aynı yöntemleri isteğin kimliği ve izniyle sunar. Minitest ile sınandı (16 Kasım 2026).
|
|
6
|
+
|
|
7
|
+
## 0.1.0
|
|
8
|
+
|
|
9
|
+
- İlk sürüm: `Feralin::Client`, Rack middleware, Rails Railtie. Henüz RubyGems'e yayınlanmadı.
|
data/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Feralin
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
data/README.md
ADDED
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
# Feralin Ruby SDK (`feralin`)
|
|
2
|
+
|
|
3
|
+
Feralin toplayıcısına (`POST /v1/batch`) sunucu tarafından olay gönderen Ruby SDK'sı. Rack middleware ve Rails Railtie içerir. Yalnız standart kütüphane kullanır (`net/http`, `json`, `securerandom`); çalışma zamanı bağımlılığı yoktur. Rails ve rack gem'in bağımlılığı değildir.
|
|
4
|
+
|
|
5
|
+
## Durum
|
|
6
|
+
|
|
7
|
+
Henüz RubyGems'e yayınlanmadı (`BLOCKED_EXTERNAL`: RubyGems hesabı, 2FA ve `feralin` adının doğrulanması gerekir). `gem install feralin` bugün bu paketi kurmaz.
|
|
8
|
+
|
|
9
|
+
Yalnız Ruby 3.3.12 (Windows, `x64-mingw-ucrt`), Rails 8.1.4.1 ve rack 3.2.8 ile koşuldu; `required_ruby_version` 3.0'a izin verse de daha eski Ruby, Rails ve rack sürümleri denenmedi. Puma ve Unicorn altında çalıştırılmadı. Gerçek `Process.fork` testi Windows'ta atlanır; çatallanma orada pid değişimi taklit edilerek sınanır, gerçek çatallanma Linux'ta henüz koşulmadı.
|
|
10
|
+
|
|
11
|
+
## Kurulum
|
|
12
|
+
|
|
13
|
+
Yayın öncesi, depodan paketleyip kurun:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
cd sdks/ruby
|
|
17
|
+
gem build feralin.gemspec
|
|
18
|
+
gem install --local feralin-0.1.0.gem
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## En kısa örnek
|
|
22
|
+
|
|
23
|
+
```ruby
|
|
24
|
+
require "feralin"
|
|
25
|
+
|
|
26
|
+
client = Feralin::Client.new(
|
|
27
|
+
ENV.fetch("FERALIN_PROJECT_KEY"), # yalnız pk_ kabul edilir, sk_ reddedilir
|
|
28
|
+
"https://collect.example.com",
|
|
29
|
+
consent: Feralin::Consent.new(analytics: true)
|
|
30
|
+
)
|
|
31
|
+
|
|
32
|
+
event = client.track("order_completed", { order_id: "ord_1", amount: 249.9 }, user_id: "user_42")
|
|
33
|
+
result = client.flush # fırlatmaz; sonuç result.error içinde
|
|
34
|
+
client.close # kalanı en çok 5 sn içinde gönderir
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
`flush` sonucu:
|
|
38
|
+
|
|
39
|
+
| Durum | `result` | Kuyruk |
|
|
40
|
+
|---|---|---|
|
|
41
|
+
| 202 | `ok?` doğru, `accepted`, `rejected`, `batch_id` | Boşalır |
|
|
42
|
+
| 4xx (429 hariç), 401 ve 403 dahil | `error` `Feralin::RejectedError` | Olaylar atılır, uygulama düşmez |
|
|
43
|
+
| 5xx, 429, ağ hatası | `error` `Feralin::TemporaryError` | Tutulur, aynı `Idempotency-Key` ile yeniden denenir |
|
|
44
|
+
|
|
45
|
+
Geri çekilme 1 sn ile 30 sn arasında üsteldir, yarım jitter eklenir ve `Retry-After` en az bekleme olarak uyulur. Açık `flush` çağrısı geri çekilmeyi beklemez.
|
|
46
|
+
|
|
47
|
+
`track` doğrulama hatasında `Feralin::InvalidEventError` fırlatır. Özellik değerleri JSON karşılığı olan türler olmalıdır; `Time`, `BigDecimal` ve benzeri nesneleri önce metne veya sayıya çevirin. `user_id` metin olmalıdır (`user.id.to_s`) ve e-posta gibi kişisel veri taşımamalıdır.
|
|
48
|
+
|
|
49
|
+
## İzin
|
|
50
|
+
|
|
51
|
+
`analytics` doğru değilse olay üretilmez ve `track` `nil` döner; varsayılan `Consent.new` izin vermez. Yalnız gerçek `true` izin sayılır.
|
|
52
|
+
|
|
53
|
+
- `advertising` doğru değilse `fr_click` olaydan çıkarılır.
|
|
54
|
+
- `client.set_consent(Feralin::Consent.new)` bekleyen olayları siler ve olay başına verilen izni de geçersiz kılar.
|
|
55
|
+
- `client.track("olay", nil, consent: izin)` yalnız o olayın iznidir. Çok kullanıcılı sunucuda izin ve kimliği istek başına tutun; `client.identify` süreçteki bütün isteklere uygulanır.
|
|
56
|
+
|
|
57
|
+
## Rack
|
|
58
|
+
|
|
59
|
+
```ruby
|
|
60
|
+
# config.ru
|
|
61
|
+
require "feralin"
|
|
62
|
+
|
|
63
|
+
Feralin.client = Feralin::Client.new(ENV.fetch("FERALIN_PROJECT_KEY"), ENV.fetch("FERALIN_COLLECT_URL"))
|
|
64
|
+
|
|
65
|
+
use Feralin::Rack::Middleware,
|
|
66
|
+
consent: ->(env) { Feralin::Consent.new(analytics: env["HTTP_COOKIE"].to_s.include?("analitik=1")) }
|
|
67
|
+
|
|
68
|
+
run ->(env) {
|
|
69
|
+
tracker = env["feralin.tracker"]
|
|
70
|
+
tracker.identify("user_42") # yalnız bu istek için
|
|
71
|
+
tracker.track("order_completed", { order_id: "ord_1" })
|
|
72
|
+
[200, { "content-type" => "text/plain" }, ["ok"]]
|
|
73
|
+
}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
- Middleware kendiliğinden olay üretmez; istek yolu ve sorgusu kişisel veri taşıyabilir.
|
|
77
|
+
- İzin çözücüsü hata verir veya `Feralin::Consent` dönmezse izin yok sayılır.
|
|
78
|
+
- `flush_after_request: true`: arka plan göndericisi kapalıyken (`flush_interval: 0`) olayları `rack.response_finished` veya `rack.after_reply` ile yanıttan sonra gönderir. Sunucu bunları sunmuyorsa gönderim yanıttan önce yapılır ve isteği uzatır.
|
|
79
|
+
|
|
80
|
+
## Rails
|
|
81
|
+
|
|
82
|
+
Gem `Gemfile` içinde olunca Railtie kendiliğinden yüklenir, middleware'i ekler ve kapanışta kuyruğu gönderir.
|
|
83
|
+
|
|
84
|
+
```ruby
|
|
85
|
+
# config/initializers/feralin.rb
|
|
86
|
+
Rails.application.config.feralin.consent_resolver = lambda do |env|
|
|
87
|
+
Feralin::Consent.new(analytics: ActionDispatch::Request.new(env).cookies["analitik"] == "1")
|
|
88
|
+
end
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
```ruby
|
|
92
|
+
class OrdersController < ApplicationController
|
|
93
|
+
def create
|
|
94
|
+
feralin.identify(current_user.public_id)
|
|
95
|
+
feralin.track("order_completed", { order_id: order.public_id })
|
|
96
|
+
end
|
|
97
|
+
end
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Anahtar ve adres `FERALIN_PROJECT_KEY` ve `FERALIN_COLLECT_URL` ortam değişkenlerinden veya `config.feralin.project_key` ve `config.feralin.collect_url` ayarlarından okunur. İkisi yoksa uygulama açılır, olay üretilmez ve durum günlüğe yazılır. Diğer ayarlar: `consent` (istemcinin varsayılan izni), `consent_resolver`, `flush_after_request`, `flush_interval`, `batch_size`, `queue_limit`, `timeout`.
|
|
101
|
+
|
|
102
|
+
## Çatallanma (Puma, Unicorn)
|
|
103
|
+
|
|
104
|
+
Kuyruk süreç başınadır. İstemci çatallanmadan önce oluşturulduysa yavru süreç ilk çağrıda boş kuyrukla ve kendi göndericisiyle başlar; üst süreçte bekleyen olaylar yavrudan gönderilmez.
|
|
105
|
+
|
|
106
|
+
## Gelir, kimlik ve hata
|
|
107
|
+
|
|
108
|
+
```ruby
|
|
109
|
+
client.track_revenue("ord_1", 4999, "TRY", product_id: "pro_monthly", user_id: "user_42")
|
|
110
|
+
client.group("acme-team", { plan: "team" }, user_id: "user_42")
|
|
111
|
+
client.set_user_properties({ plan: "pro" }, user_id: "user_42")
|
|
112
|
+
begin
|
|
113
|
+
odeme_al
|
|
114
|
+
rescue StandardError => e
|
|
115
|
+
client.capture_error(e, user_id: "user_42")
|
|
116
|
+
end
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
- `track_revenue` → `feralin_purchase`: tutar küçük birimde `Integer`, ISO 4217; kurallar diğer SDK'larla aynıdır, sözleşme dışı girdide `InvalidEventError`. `verified` hiçbir zaman gönderilmez. SDK sözleşmesinde iade olayı yoktur.
|
|
120
|
+
- `group` → `fr_group`, `set_user_properties` → `fr_user_properties`: kişisel veriye benzeyen anahtar, doğrulama alanı ve sınır dışı değer istemcide düşer; geçersizse `nil`.
|
|
121
|
+
- `capture_error` → `fr_error` (Android SDK ile aynı gövde): hata sınıfı adı, temizlenmiş en çok 200 karakterlik mesaj, gem ve standart kütüphane dışı ilk beş çerçevenin parmak izi, üst çerçeve (`işlev@dosya.rb`) ve en çok 5 konum (dosya taban adı, satır, işlev). Ham backtrace gitmez; 60 saniyede en çok 20 olay, aynı parmak izi için en çok 3. Kurucu: `app_version:`, `error_sample_rate:`. Fırlatmaz.
|
|
122
|
+
- Rack'te `env["feralin.tracker"]` aynı dört yöntemi isteğin kimliği ve izniyle sunar.
|
|
123
|
+
|
|
124
|
+
## Desteklenmeyenler
|
|
125
|
+
|
|
126
|
+
- Kalıcı kuyruk: olaylar bellektedir, süreç ölürse kaybolur. Sınır aşılırsa en eski olay atılır.
|
|
127
|
+
- `reset`, global özellikler, otomatik (Rack) hata yakalama, OTel izleme.
|
|
128
|
+
- Sidekiq veya ActiveJob bütünleşmesi. İş sürecinde `Feralin::Client` doğrudan kullanılabilir.
|
|
129
|
+
- Otomatik sayfa veya istek olayı, parmak izi, `fr_click` okuma. `verified`, `tenant_id` ve `project_id` istemciden gönderilmez.
|
|
130
|
+
|
|
131
|
+
## Geliştirme
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
cd sdks/ruby
|
|
135
|
+
ruby -S rake test
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
Gerçek rack ve Rails ile tümleşik test (genel gem dizinine dokunmaz):
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
cd sdks/ruby
|
|
142
|
+
GEM_HOME="$PWD/vendor/gems" GEM_PATH="$PWD/vendor/gems" ruby -S gem install railties rack tzinfo-data --no-document
|
|
143
|
+
GEM_HOME="$PWD/vendor/gems" GEM_PATH="$PWD/vendor/gems" ruby -S rake test:rails
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
`tzinfo-data` yalnız Windows'ta gerekir; Rails orada sistem saat dilimi verisi bulamaz.
|
|
147
|
+
|
|
148
|
+
Gerçek toplayıcıyla uçtan uca test (yalnız test veritabanı verin):
|
|
149
|
+
|
|
150
|
+
```bash
|
|
151
|
+
DATABASE_URL='postgres://...' COLLECT_ADDR=127.0.0.1:4712 node scripts/sdk-e2e/run.mjs ruby
|
|
152
|
+
```
|