typesense 5.0.0 → 5.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.
Files changed (56) hide show
  1. checksums.yaml +4 -4
  2. data/.github/workflows/tests.yml +2 -2
  3. data/.rubocop.yml +9 -1
  4. data/Gemfile +3 -7
  5. data/README.md +41 -0
  6. data/docker-compose.yml +1 -1
  7. data/flake.lock +61 -0
  8. data/flake.nix +56 -0
  9. data/lib/typesense/alias.rb +12 -0
  10. data/lib/typesense/aliases.rb +20 -0
  11. data/lib/typesense/analytics.rb +19 -0
  12. data/lib/typesense/analytics_events.rb +12 -0
  13. data/lib/typesense/analytics_events_v1.rb +6 -0
  14. data/lib/typesense/analytics_rule.rb +20 -1
  15. data/lib/typesense/analytics_rule_v1.rb +12 -0
  16. data/lib/typesense/analytics_rules.rb +34 -2
  17. data/lib/typesense/analytics_rules_v1.rb +20 -0
  18. data/lib/typesense/analytics_v1.rb +20 -0
  19. data/lib/typesense/api_call.rb +72 -5
  20. data/lib/typesense/client.rb +179 -2
  21. data/lib/typesense/collection.rb +56 -1
  22. data/lib/typesense/collections.rb +20 -0
  23. data/lib/typesense/configuration.rb +18 -4
  24. data/lib/typesense/curation_set.rb +29 -0
  25. data/lib/typesense/curation_set_item.rb +18 -0
  26. data/lib/typesense/curation_set_items.rb +14 -0
  27. data/lib/typesense/curation_sets.rb +20 -0
  28. data/lib/typesense/debug.rb +6 -0
  29. data/lib/typesense/document.rb +18 -0
  30. data/lib/typesense/documents.rb +62 -0
  31. data/lib/typesense/health.rb +6 -0
  32. data/lib/typesense/key.rb +12 -0
  33. data/lib/typesense/keys.rb +26 -0
  34. data/lib/typesense/metrics.rb +6 -0
  35. data/lib/typesense/multi_search.rb +8 -0
  36. data/lib/typesense/nl_search_model.rb +18 -0
  37. data/lib/typesense/nl_search_models.rb +20 -0
  38. data/lib/typesense/operations.rb +6 -0
  39. data/lib/typesense/override.rb +12 -0
  40. data/lib/typesense/overrides.rb +20 -0
  41. data/lib/typesense/preset.rb +12 -0
  42. data/lib/typesense/presets.rb +20 -0
  43. data/lib/typesense/stats.rb +6 -0
  44. data/lib/typesense/stemming.rb +11 -0
  45. data/lib/typesense/stemming_dictionaries.rb +20 -0
  46. data/lib/typesense/stemming_dictionary.rb +6 -0
  47. data/lib/typesense/synonym.rb +13 -0
  48. data/lib/typesense/synonym_set.rb +36 -0
  49. data/lib/typesense/synonym_set_item.rb +47 -0
  50. data/lib/typesense/synonym_set_items.rb +39 -0
  51. data/lib/typesense/synonym_sets.rb +20 -0
  52. data/lib/typesense/synonyms.rb +21 -0
  53. data/lib/typesense/version.rb +1 -1
  54. data/lib/typesense.rb +2 -0
  55. data/typesense.gemspec +5 -5
  56. metadata +46 -11
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 4b23c932504c838fa3f2e1f81799177bf87ba5ca4707a51166a25ddfe4c4b122
4
- data.tar.gz: dc707abbc7a0a9407e0dee23fc93aae5da56cd5c6e9829eae932a578b476d307
3
+ metadata.gz: ac5977e88e32a761db4a539399269a8408f1466c4cfb03be86c41709b1c1963a
4
+ data.tar.gz: 12fcd5d973d1f1b01c12b755ff0bbb8240c61074b9d7b629ab8b68e3f27da00e
5
5
  SHA512:
6
- metadata.gz: 34d84e8e3f542b1adf96200bef90e35754ffa940a43860e72e9e60fe4cf401cad013678a4a42f0253470af31fbbb9d39e2455ce79971348821b479c751d5073b
7
- data.tar.gz: 6afb7470a13190ec849e9ba01c64a4f45866878291afcbb606998f94b97ba21f7fa58656dd8285d3448072476d96c04920f8fabe8f7fe9b7f8d6928d3d482293
6
+ metadata.gz: c45c98f88c8a751f7b75c36217c8c5c1246a0c4279a71d055f19b018545b73cb95a82f8970802659368f8c783dbaf55d62bd127a6da8501b4133c50b686e99d8
7
+ data.tar.gz: 4ee328734704c4dfaf6401954ac4ece90e72291f1995114739cdeadd7436befdc0692f33a32a5e8a6e3bc0210221ad7a2171122bbc3f5d9287babb2f042b8614
@@ -10,10 +10,10 @@ jobs:
10
10
  runs-on: ubuntu-latest
11
11
  strategy:
12
12
  matrix:
13
- ruby-version: ['3.0', '3.2', '3.3', '3.4']
13
+ ruby-version: ['3.0', '3.2', '3.3', '3.4', '4.0']
14
14
  services:
15
15
  typesense:
16
- image: typesense/typesense:30.0.alpha1
16
+ image: typesense/typesense:30.2
17
17
  ports:
18
18
  - 8108:8108
19
19
  volumes:
data/.rubocop.yml CHANGED
@@ -2,7 +2,7 @@ plugins: rubocop-rspec
2
2
 
3
3
  AllCops:
4
4
  NewCops: enable
5
- TargetRubyVersion: 2.7
5
+ TargetRubyVersion: 3.0
6
6
 
7
7
  Style/Documentation:
8
8
  Enabled: false
@@ -47,5 +47,13 @@ RSpec/ExampleLength:
47
47
  RSpec/MultipleExpectations:
48
48
  Enabled: false
49
49
 
50
+ RSpec/Output:
51
+ Exclude:
52
+ - spec/spec_helper.rb
53
+
54
+ Naming/PredicateMethod:
55
+ Exclude:
56
+ - spec/spec_helper.rb
57
+
50
58
  Style/HashSyntax:
51
59
  Enabled: false # We still want to support older versions of Ruby
data/Gemfile CHANGED
@@ -6,17 +6,13 @@ git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
6
6
 
7
7
  # Dev dependencies
8
8
  gem 'awesome_print', '~> 1.8'
9
- gem 'bundler', '~> 2.0'
10
- gem 'codecov', '~> 0.1'
11
- gem 'erb'
9
+ gem 'bundler', '>= 2.0'
12
10
  gem 'guard', '~> 2.16'
13
11
  gem 'guard-rubocop', '~> 1.3'
14
12
  gem 'rake', '~> 13.0'
15
13
  gem 'rspec', '~> 3.9'
16
- gem 'rspec_junit_formatter', '~> 0.4'
17
- gem 'rspec-legacy_formatters', '~> 1.0' # For codecov formatter
18
- gem 'rubocop', '1.72.2'
19
- gem 'rubocop-rspec', '~> 3.6', require: false
14
+ gem 'rubocop', '~> 1.90'
15
+ gem 'rubocop-rspec', '~> 3.9', require: false
20
16
  gem 'simplecov', '~> 0.18'
21
17
  gem 'timecop', '~> 0.9'
22
18
  gem 'webmock', '~> 3.8'
data/README.md CHANGED
@@ -29,6 +29,47 @@ Here are some examples with inline comments that walk you through how to use the
29
29
 
30
30
  Tests are also a good place to know how the the library works internally: [spec](spec)
31
31
 
32
+ ### Error handling
33
+
34
+ Error responses from Typesense raise a subclass of `Typesense::Error`. The exception's `message` is the `message` from the API response, and the underlying Faraday response is available as `e.data[:response]` if you need the HTTP status, headers, or raw body:
35
+
36
+ ```ruby
37
+ begin
38
+ client.collections['unknown'].retrieve
39
+ rescue Typesense::Error::ObjectNotFound => e
40
+ e.message # => "Not Found"
41
+ e.data[:response].status # => 404
42
+ e.data[:response].body # => raw response body
43
+ end
44
+ ```
45
+
46
+ Status codes map to these classes: `RequestMalformed` (400), `RequestUnauthorized` (401), `ObjectNotFound` (404), `ObjectAlreadyExists` (409), `ObjectUnprocessable` (422), `ServerError` (5xx), `HTTPStatus0Error` (status 0), and `HTTPError` (any other non-2xx status).
47
+
48
+ 5xx responses and network errors are retried first. Once retries run out, the last error is re-raised, so a network failure surfaces as the original Faraday or `Errno` exception rather than a `Typesense::Error`.
49
+
50
+ ### Keep-alive connections
51
+
52
+ By default, the client opens a fresh HTTP connection (and TLS handshake) for every request. For high-traffic applications this can dominate request latency. Setting `keep_alive_connections: true` enables persistent connections via the `:net_http_persistent` Faraday adapter:
53
+
54
+ ```ruby
55
+ Typesense::Client.new(
56
+ api_key: ENV['TYPESENSE_API_KEY'],
57
+ nodes: [{ host: 'localhost', port: 8108, protocol: 'https' }],
58
+ connection_timeout_seconds: 3,
59
+ num_retries: 1,
60
+ keep_alive_connections: true
61
+ )
62
+ ```
63
+
64
+ Notes:
65
+
66
+ - Connections are cached per `(thread, node)`. `Net::HTTP` is not thread-safe, so each thread maintains its own keep-alive socket to each Typesense node, and the existing node round-robin still works.
67
+ - A cached connection is dropped automatically when a network error occurs, so retries open a fresh socket. We recommend setting `num_retries` to at least `1` so the gem can recover from a server- or load-balancer-side idle timeout transparently.
68
+ - Idle sockets are closed after 30 seconds by default. Override with `keep_alive_idle_timeout_seconds` to match or stay under your load balancer's idle timeout.
69
+ - The underlying `net_http_persistent` adapter holds at most `keep_alive_pool_size` sockets per origin (default `1`, which matches the per-`(thread, node)` cache above). The default of `1` is the safe choice for the vast majority of users — because we already cache one Faraday connection per `(thread, node)` and `Net::HTTP` is not thread-safe, a single socket per pool is all the adapter needs. Only raise this if you have a specific reason to keep additional sockets warm per origin (e.g. a non-standard concurrency model layered on top of this client); a larger pool will not increase request throughput on its own.
70
+ - `keep_alive_idle_timeout_seconds` and `keep_alive_pool_size` are only valid when `keep_alive_connections: true`; setting them otherwise raises `Typesense::Error::MissingConfiguration`.
71
+ - The option defaults to `false`, so upgrading the gem does not change behaviour until you opt in.
72
+
32
73
  ## Compatibility
33
74
 
34
75
  | Typesense Server | typesense-ruby |
data/docker-compose.yml CHANGED
@@ -1,6 +1,6 @@
1
1
  services:
2
2
  typesense:
3
- image: typesense/typesense:29.0
3
+ image: typesense/typesense:30.2
4
4
  ports:
5
5
  - "127.0.0.1:8108:8108"
6
6
  volumes:
data/flake.lock ADDED
@@ -0,0 +1,61 @@
1
+ {
2
+ "nodes": {
3
+ "flake-utils": {
4
+ "inputs": {
5
+ "systems": "systems"
6
+ },
7
+ "locked": {
8
+ "lastModified": 1731533236,
9
+ "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=",
10
+ "owner": "numtide",
11
+ "repo": "flake-utils",
12
+ "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
13
+ "type": "github"
14
+ },
15
+ "original": {
16
+ "owner": "numtide",
17
+ "repo": "flake-utils",
18
+ "type": "github"
19
+ }
20
+ },
21
+ "nixpkgs": {
22
+ "locked": {
23
+ "lastModified": 1779560665,
24
+ "narHash": "sha256-tpyBcxPpcQb8ukyNF7DoCwfSY3VPsxHoYwj00Cayv5o=",
25
+ "owner": "NixOS",
26
+ "repo": "nixpkgs",
27
+ "rev": "64c08a7ca051951c8eae34e3e3cb1e202fe36786",
28
+ "type": "github"
29
+ },
30
+ "original": {
31
+ "owner": "NixOS",
32
+ "ref": "nixos-unstable",
33
+ "repo": "nixpkgs",
34
+ "type": "github"
35
+ }
36
+ },
37
+ "root": {
38
+ "inputs": {
39
+ "flake-utils": "flake-utils",
40
+ "nixpkgs": "nixpkgs"
41
+ }
42
+ },
43
+ "systems": {
44
+ "locked": {
45
+ "lastModified": 1681028828,
46
+ "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
47
+ "owner": "nix-systems",
48
+ "repo": "default",
49
+ "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
50
+ "type": "github"
51
+ },
52
+ "original": {
53
+ "owner": "nix-systems",
54
+ "repo": "default",
55
+ "type": "github"
56
+ }
57
+ }
58
+ },
59
+ "root": "root",
60
+ "version": 7
61
+ }
data/flake.nix ADDED
@@ -0,0 +1,56 @@
1
+ {
2
+ description = "Nix development environment for the Typesense Ruby client";
3
+
4
+ inputs = {
5
+ nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
6
+ flake-utils.url = "github:numtide/flake-utils";
7
+ };
8
+
9
+ outputs = { self, nixpkgs, flake-utils }:
10
+ flake-utils.lib.eachDefaultSystem (system:
11
+ let
12
+ pkgs = import nixpkgs {
13
+ inherit system;
14
+ };
15
+
16
+ ruby = pkgs.ruby_3_4;
17
+ in
18
+ {
19
+ devShells.default = pkgs.mkShell {
20
+ packages = with pkgs; [
21
+ ruby
22
+ bundler
23
+ git
24
+ curl
25
+ pkg-config
26
+ openssl
27
+ libyaml
28
+ zlib
29
+ libffi
30
+ docker
31
+ docker-compose
32
+ ];
33
+
34
+ shellHook = ''
35
+ export BUNDLE_PATH="$PWD/.bundle"
36
+ export BUNDLE_BIN="$PWD/.bundle/bin"
37
+ export BUNDLE_APP_CONFIG="$PWD/.bundle/config"
38
+ export GEM_HOME="$PWD/.bundle/ruby"
39
+ export PATH="$BUNDLE_BIN:$GEM_HOME/bin:$PATH"
40
+
41
+ cat <<'EOF'
42
+ Typesense Ruby dev shell
43
+
44
+ First-time setup:
45
+ bundle install
46
+
47
+ Common commands:
48
+ bundle exec rubocop
49
+ bundle exec rspec --format documentation
50
+
51
+ Integration tests expect Docker to be running.
52
+ EOF
53
+ '';
54
+ };
55
+ });
56
+ }
@@ -7,10 +7,22 @@ module Typesense
7
7
  @api_call = api_call
8
8
  end
9
9
 
10
+ # Find out which collection an alias points to by fetching it
11
+ #
12
+ # @example
13
+ # client.aliases['my-alias'].retrieve
14
+ #
15
+ # @see https://typesense.org/docs/latest/api/collection-alias.html#retrieve-an-alias
10
16
  def retrieve
11
17
  @api_call.get(endpoint_path)
12
18
  end
13
19
 
20
+ # Delete an alias
21
+ #
22
+ # @example
23
+ # client.aliases['my-alias'].delete
24
+ #
25
+ # @see https://typesense.org/docs/latest/api/collection-alias.html#delete-an-alias
14
26
  def delete
15
27
  @api_call.delete(endpoint_path)
16
28
  end
@@ -9,14 +9,34 @@ module Typesense
9
9
  @aliases = {}
10
10
  end
11
11
 
12
+ # Create or update a collection alias.
13
+ #
14
+ # @example
15
+ # client.aliases.upsert('my-alias', 'collection_name' => 'products')
16
+ #
17
+ # @see https://typesense.org/docs/latest/api/collection-alias.html#create-or-update-an-alias
12
18
  def upsert(alias_name, mapping)
13
19
  @api_call.put(endpoint_path(alias_name), mapping)
14
20
  end
15
21
 
22
+ # List all aliases and the corresponding collections that they map to.
23
+ #
24
+ # @example
25
+ # client.aliases.retrieve
26
+ #
27
+ # @see https://typesense.org/docs/latest/api/collection-alias.html#list-all-aliases
16
28
  def retrieve
17
29
  @api_call.get(RESOURCE_PATH)
18
30
  end
19
31
 
32
+ # Access an individual collection alias by name.
33
+ #
34
+ # @example
35
+ # client.aliases['my-alias'].retrieve
36
+ #
37
+ # @see https://typesense.org/docs/latest/api/collection-alias.html
38
+ #
39
+ # @return [Alias]
20
40
  def [](alias_name)
21
41
  @aliases[alias_name] ||= Alias.new(alias_name, @api_call)
22
42
  end
@@ -8,10 +8,29 @@ module Typesense
8
8
  @api_call = api_call
9
9
  end
10
10
 
11
+ # Access the analytics rules resource. Use it to list or create rules, or as an array
12
+ # to access a single rule by ID.
13
+ #
14
+ # @example
15
+ # client.analytics.rules.retrieve
16
+ # @example
17
+ # client.analytics.rules['rule-1'].retrieve
18
+ #
19
+ # @see https://typesense.org/docs/latest/api/analytics-query-suggestions.html
20
+ #
21
+ # @return [AnalyticsRules]
11
22
  def rules
12
23
  @rules ||= AnalyticsRules.new(@api_call)
13
24
  end
14
25
 
26
+ # Access the analytics events resource to send analytics events.
27
+ #
28
+ # @example
29
+ # client.analytics.events.create('type' => 'click', 'name' => 'products_click', 'data' => {})
30
+ #
31
+ # @see https://typesense.org/docs/latest/api/analytics-query-suggestions.html
32
+ #
33
+ # @return [AnalyticsEvents]
15
34
  def events
16
35
  @events ||= AnalyticsEvents.new(@api_call)
17
36
  end
@@ -8,10 +8,22 @@ module Typesense
8
8
  @api_call = api_call
9
9
  end
10
10
 
11
+ # Submit a single analytics event. The event must correspond to an existing analytics rule by name.
12
+ #
13
+ # @example
14
+ # client.analytics.events.create('type' => 'click', 'name' => 'products_click', 'data' => {})
15
+ #
16
+ # @see https://typesense.org/docs/latest/api/analytics-query-suggestions.html
11
17
  def create(params)
12
18
  @api_call.post(self.class::RESOURCE_PATH, params)
13
19
  end
14
20
 
21
+ # Retrieve the most recent events for a user and rule.
22
+ #
23
+ # @example
24
+ # client.analytics.events.retrieve('user_id' => 'u1', 'name' => 'products_click', 'n' => 10)
25
+ #
26
+ # @see https://typesense.org/docs/latest/api/analytics-query-suggestions.html
15
27
  def retrieve(params = {})
16
28
  @api_call.get(self.class::RESOURCE_PATH, params)
17
29
  end
@@ -8,6 +8,12 @@ module Typesense
8
8
  @api_call = api_call
9
9
  end
10
10
 
11
+ # Submit a single legacy v1 analytics event. The event must correspond to an existing analytics rule by name.
12
+ #
13
+ # @example
14
+ # client.analytics_v1.events.create('type' => 'click', 'name' => 'products_click', 'data' => {})
15
+ #
16
+ # @see https://typesense.org/docs/29.0/api/analytics-query-suggestions.html
11
17
  def create(params)
12
18
  @api_call.post(endpoint_path, params)
13
19
  end
@@ -7,17 +7,36 @@ module Typesense
7
7
  @api_call = api_call
8
8
  end
9
9
 
10
+ # Retrieve the details of an analytics rule, given it's name
11
+ #
12
+ # @example
13
+ # client.analytics.rules['rule-1'].retrieve
14
+ #
15
+ # @see https://typesense.org/docs/latest/api/analytics-query-suggestions.html
10
16
  def retrieve
11
17
  @api_call.get(endpoint_path)
12
18
  end
13
19
 
20
+ # Permanently deletes an analytics rule, given it's name
21
+ #
22
+ # @example
23
+ # client.analytics.rules['rule-1'].delete
24
+ #
25
+ # @see https://typesense.org/docs/latest/api/analytics-query-suggestions.html
14
26
  def delete
15
27
  @api_call.delete(endpoint_path)
16
28
  end
17
29
 
18
- def update(params)
30
+ # Create or update an analytics rule with the given name.
31
+ #
32
+ # @example
33
+ # client.analytics.rules['products_click_counter'].upsert('type' => 'counter', 'collection' => 'products', 'event_type' => 'click', 'params' => { 'counter_field' => 'popularity', 'weight' => 1 })
34
+ #
35
+ # @see https://typesense.org/docs/latest/api/analytics-query-suggestions.html
36
+ def upsert(params)
19
37
  @api_call.put(endpoint_path, params)
20
38
  end
39
+ alias update upsert
21
40
 
22
41
  private
23
42
 
@@ -7,10 +7,22 @@ module Typesense
7
7
  @api_call = api_call
8
8
  end
9
9
 
10
+ # Retrieve a legacy v1 analytics rule by name.
11
+ #
12
+ # @example
13
+ # client.analytics_v1.rules['rule-1'].retrieve
14
+ #
15
+ # @see https://typesense.org/docs/29.0/api/analytics-query-suggestions.html
10
16
  def retrieve
11
17
  @api_call.get(endpoint_path)
12
18
  end
13
19
 
20
+ # Delete a legacy v1 analytics rule by name.
21
+ #
22
+ # @example
23
+ # client.analytics_v1.rules['rule-1'].delete
24
+ #
25
+ # @see https://typesense.org/docs/29.0/api/analytics-query-suggestions.html
14
26
  def delete
15
27
  @api_call.delete(endpoint_path)
16
28
  end
@@ -8,14 +8,46 @@ module Typesense
8
8
  @api_call = api_call
9
9
  end
10
10
 
11
+ # Create one or more analytics rules. You can send a single rule object or an array of rule objects.
12
+ #
13
+ # @example
14
+ # client.analytics.rules.create('name' => 'products_query_hits', 'type' => 'popular_queries', 'params' => {})
15
+ #
16
+ # @see https://typesense.org/docs/latest/api/analytics-query-suggestions.html
11
17
  def create(rules)
12
18
  @api_call.post(self.class::RESOURCE_PATH, rules)
13
19
  end
14
20
 
15
- def retrieve
16
- @api_call.get(self.class::RESOURCE_PATH)
21
+ # Create or update an analytics rule with the given name.
22
+ #
23
+ # @example
24
+ # client.analytics.rules.upsert('products_click_counter', 'type' => 'counter', 'collection' => 'products', 'event_type' => 'click', 'params' => { 'counter_field' => 'popularity', 'weight' => 1 })
25
+ #
26
+ # @see https://typesense.org/docs/latest/api/analytics-query-suggestions.html
27
+ def upsert(rule_name, params)
28
+ @api_call.put("#{self.class::RESOURCE_PATH}/#{URI.encode_www_form_component(rule_name)}", params)
17
29
  end
18
30
 
31
+ # Retrieve all analytics rules. Pass `rule_tag` to only retrieve the rules with that tag.
32
+ #
33
+ # @example
34
+ # client.analytics.rules.retrieve
35
+ # @example
36
+ # client.analytics.rules.retrieve(rule_tag: 'homepage')
37
+ #
38
+ # @see https://typesense.org/docs/latest/api/analytics-query-suggestions.html
39
+ def retrieve(params = {})
40
+ @api_call.get(self.class::RESOURCE_PATH, params)
41
+ end
42
+
43
+ # Access an individual analytics rule by name.
44
+ #
45
+ # @example
46
+ # client.analytics.rules['rule-1'].retrieve
47
+ #
48
+ # @see https://typesense.org/docs/latest/api/analytics-query-suggestions.html
49
+ #
50
+ # @return [AnalyticsRule]
19
51
  def [](rule_name)
20
52
  AnalyticsRule.new(rule_name, @api_call)
21
53
  end
@@ -9,14 +9,34 @@ module Typesense
9
9
  @analytics_rules = {}
10
10
  end
11
11
 
12
+ # Upsert a legacy v1 analytics rule by name.
13
+ #
14
+ # @example
15
+ # client.analytics_v1.rules.upsert('products_query_hits', 'type' => 'popular_queries', 'params' => {})
16
+ #
17
+ # @see https://typesense.org/docs/29.0/api/analytics-query-suggestions.html
12
18
  def upsert(rule_name, params)
13
19
  @api_call.put(endpoint_path(rule_name), params)
14
20
  end
15
21
 
22
+ # Retrieve all legacy v1 analytics rules.
23
+ #
24
+ # @example
25
+ # client.analytics_v1.rules.retrieve
26
+ #
27
+ # @see https://typesense.org/docs/29.0/api/analytics-query-suggestions.html
16
28
  def retrieve
17
29
  @api_call.get(endpoint_path)
18
30
  end
19
31
 
32
+ # Access an individual legacy v1 analytics rule by name.
33
+ #
34
+ # @example
35
+ # client.analytics_v1.rules['rule-1'].retrieve
36
+ #
37
+ # @see https://typesense.org/docs/29.0/api/analytics-query-suggestions.html
38
+ #
39
+ # @return [AnalyticsRuleV1]
20
40
  def [](rule_name)
21
41
  @analytics_rules[rule_name] ||= AnalyticsRuleV1.new(rule_name, @api_call)
22
42
  end
@@ -1,6 +1,7 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Typesense
4
+ # @deprecated Deprecated starting with Typesense Server v30. Please migrate to `client.analytics` (new Analytics APIs).
4
5
  class AnalyticsV1
5
6
  RESOURCE_PATH = '/analytics'
6
7
 
@@ -8,10 +9,29 @@ module Typesense
8
9
  @api_call = api_call
9
10
  end
10
11
 
12
+ # Access the legacy v1 analytics rules resource. Use it to list or upsert rules, or as an array
13
+ # to access a single rule by ID.
14
+ #
15
+ # @example
16
+ # client.analytics_v1.rules.retrieve
17
+ # @example
18
+ # client.analytics_v1.rules['rule-1'].retrieve
19
+ #
20
+ # @see https://typesense.org/docs/29.0/api/analytics-query-suggestions.html
21
+ #
22
+ # @return [AnalyticsRulesV1]
11
23
  def rules
12
24
  @rules ||= AnalyticsRulesV1.new(@api_call)
13
25
  end
14
26
 
27
+ # Access the legacy v1 analytics events resource to send analytics events.
28
+ #
29
+ # @example
30
+ # client.analytics_v1.events.create('type' => 'click', 'name' => 'products_click', 'data' => {})
31
+ #
32
+ # @see https://typesense.org/docs/29.0/api/analytics-query-suggestions.html
33
+ #
34
+ # @return [AnalyticsEventsV1]
15
35
  def events
16
36
  @events ||= AnalyticsEventsV1.new(@api_call)
17
37
  end
@@ -19,9 +19,18 @@ module Typesense
19
19
  @healthcheck_interval_seconds = @configuration.healthcheck_interval_seconds
20
20
  @num_retries_per_request = @configuration.num_retries
21
21
  @retry_interval_seconds = @configuration.retry_interval_seconds
22
+ @keep_alive_connections = @configuration.keep_alive_connections
23
+ @keep_alive_idle_timeout_seconds = @configuration.keep_alive_idle_timeout_seconds
24
+ @keep_alive_pool_size = @configuration.keep_alive_pool_size
22
25
 
23
26
  @logger = @configuration.logger
24
27
 
28
+ # Per-instance key for the thread-local connection cache so multiple
29
+ # Typesense::Client instances in the same process do not share sockets.
30
+ @thread_connections_key = :"_typesense_api_call_connections_#{object_id}"
31
+
32
+ require 'faraday/net_http_persistent' if @keep_alive_connections
33
+
25
34
  initialize_metadata_for_nodes
26
35
  @current_node_index = -1
27
36
  end
@@ -69,14 +78,14 @@ module Typesense
69
78
  @logger.debug "Attempting #{method.to_s.upcase} request Try ##{num_tries} to Node #{node[:index]}"
70
79
 
71
80
  begin
72
- conn = Faraday.new(uri_for(endpoint, node)) do |f|
73
- f.options.timeout = @connection_timeout_seconds
74
- f.options.open_timeout = @connection_timeout_seconds
75
- end
81
+ conn, request_url = connection_and_url_for(endpoint, node)
76
82
 
77
83
  headers = default_headers.merge(additional_headers)
78
84
 
85
+ # The URL is set on the request instead of being passed to the verb. Faraday
86
+ # looks up proxy settings again for every absolute URL passed to the verb.
79
87
  response = conn.send(method) do |req|
88
+ req.url(request_url) unless request_url.nil?
80
89
  req.headers = headers
81
90
  req.params = query_parameters unless query_parameters.nil?
82
91
  unless body_parameters.nil?
@@ -108,6 +117,9 @@ module Typesense
108
117
  # Rescue network layer exceptions and HTTP 5xx errors, so the loop can continue.
109
118
  # Using loops for retries instead of rescue...retry to maintain consistency with client libraries in
110
119
  # other languages that might not support the same construct.
120
+ # Drop the cached keep-alive connection (if any): the underlying socket is likely
121
+ # half-closed and reusing it would just fail again on retry.
122
+ discard_connection(node) if @keep_alive_connections
111
123
  set_node_healthcheck(node, is_healthy: false)
112
124
  last_exception = e
113
125
  @logger.warn "Request #{method}:#{uri_for(endpoint, node)} to Node #{node[:index]} failed due to \"#{e.class}: #{e.message}\""
@@ -121,8 +133,63 @@ module Typesense
121
133
 
122
134
  private
123
135
 
136
+ # Faraday 2.9.2 and later only treat a request URL as absolute when it starts
137
+ # with a lower-case "http://" or "https://".
124
138
  def uri_for(endpoint, node)
125
- "#{node[:protocol]}://#{node[:host]}:#{node[:port]}#{endpoint}"
139
+ "#{node[:protocol].to_s.downcase}://#{node[:host]}:#{node[:port]}#{endpoint}"
140
+ end
141
+
142
+ # Returns [connection, request_url]. When keep-alive is enabled, the connection
143
+ # is cached per (thread, node) and each request gets the full URL. Faraday merges
144
+ # a relative path into the base URL, and that merge drops "." and ".." segments.
145
+ # A delete of document ".." would then delete its whole collection. When keep-alive
146
+ # is disabled, the original behaviour is preserved: a fresh Faraday is built for
147
+ # the full per-request URL, so existing callers and stubs see no change.
148
+ def connection_and_url_for(endpoint, node)
149
+ if @keep_alive_connections
150
+ [connection_for(node), uri_for(endpoint, node)]
151
+ else
152
+ [build_one_shot_connection(endpoint, node), nil]
153
+ end
154
+ end
155
+
156
+ def build_one_shot_connection(endpoint, node)
157
+ Faraday.new(uri_for(endpoint, node)) do |f|
158
+ f.options.timeout = @connection_timeout_seconds
159
+ f.options.open_timeout = @connection_timeout_seconds
160
+ end
161
+ end
162
+
163
+ # Net::HTTP is not thread-safe, so connections are cached per (thread, node)
164
+ # rather than shared across threads.
165
+ def connection_for(node)
166
+ thread_connections[connection_key(node)] ||= build_keep_alive_connection(node)
167
+ end
168
+
169
+ def discard_connection(node)
170
+ conn = thread_connections.delete(connection_key(node))
171
+ conn&.close if conn.respond_to?(:close)
172
+ end
173
+
174
+ def thread_connections
175
+ Thread.current[@thread_connections_key] ||= {}
176
+ end
177
+
178
+ def connection_key(node)
179
+ "#{node[:protocol]}://#{node[:host]}:#{node[:port]}"
180
+ end
181
+
182
+ def build_keep_alive_connection(node)
183
+ Faraday.new(url: connection_key(node)) do |f|
184
+ f.options.timeout = @connection_timeout_seconds
185
+ f.options.open_timeout = @connection_timeout_seconds
186
+ # pool_size defaults to 1: we already cache one Faraday connection per
187
+ # (thread, node), and Net::HTTP is not thread-safe — so a single socket
188
+ # per pool is the safe default. Override only with a specific reason.
189
+ f.adapter :net_http_persistent, pool_size: @keep_alive_pool_size do |http|
190
+ http.idle_timeout = @keep_alive_idle_timeout_seconds
191
+ end
192
+ end
126
193
  end
127
194
 
128
195
  ## Attempts to find the next healthy node, looping through the list of nodes once.