typesense 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c74454a48a4f170bbb99bb5e382199c8842e84ec5d2fbd6198106df89b45977
-  data.tar.gz: ca4772c87e84fabe0cef3af42bfb6e1bb889e305b402d9a2e2f83b10bdbe6d1b
+  metadata.gz: ec69deb240d0c343346d128161aa74fe12ab18e7f79007dfa24ac16738c46237
+  data.tar.gz: e681fcd5f9b1241054f3c786ee5e6eebad45c1ddc1705311bf7a45ea6551a23f
 SHA512:
-  metadata.gz: d1ab99d6e52d15257c8e664d765b1debb063d151d364916b273cef1658537dadcd0241e76fffa5807be50b15c83891b76c2aaef7105c875be2c3bb70728b88e0
-  data.tar.gz: db20bce0c42a7713a3c5fa25ca1c7a17bb6724bd8949b5dc16202d11538b348d806d960f0def0712e118d856184da8650a3b12ba861037754e20e172856d38c0
+  metadata.gz: f6dd0dfd751499e1ec32cfd45935038df7ad219c498f433745fd8855439ef5136a7df7c47491f37fa9940d8bc1f1d02cfcc5aa77f6c4a154256f6ebe4dcb5c32
+  data.tar.gz: 7ef2d64aa701054a756222bc18dc19c9b3e282dbb6cc8789a47fe901d5716d67faaacf0c8fe1ed5b3de7cf1f06a1af11621e77ec633a4dfb6722e5bb0ed6908f

data/.rubocop.yml

@@ -11,3 +11,6 @@ Metrics/BlockLength:
     - 'spec/**/*'
     - 'Gemfile'
     - 'typesense.gemspec'
+
+Style/Documentation:
+  Enabled: false

data/.rubocop_todo.yml

@@ -17,6 +17,7 @@ Lint/SuppressedException:
   Exclude:
     - 'examples/collections_and_documents.rb'
     - 'examples/search.rb'
+    - 'examples/keys.rb'
 
 # Offense count: 3
 # Configuration parameters: IgnoredMethods.
@@ -49,6 +50,8 @@ RSpec/ExampleLength:
   Exclude:
     - 'spec/typesense/alias_spec.rb'
     - 'spec/typesense/aliases_spec.rb'
+    - 'spec/typesense/key_spec.rb'
+    - 'spec/typesense/keys_spec.rb'
     - 'spec/typesense/api_call_spec.rb'
     - 'spec/typesense/collection_spec.rb'
     - 'spec/typesense/collections_spec.rb'

data/README.md

@@ -33,8 +33,9 @@ Tests are also a good place to know how the the library works internally: [spec]
 
 | Typesense Server | typesense-ruby |
 |------------------|----------------|
+| \>= v0.12.1 | \>= v0.5.0 |
+| \>= v0.12.0 | \>= v0.4.0 |
 | <= v0.11 | <= v0.3.0 |
-| \>= v0.12 | \>= v0.4.0 |
 
 ## Development
 

data/examples/client_initialization.rb

@@ -11,7 +11,7 @@ AwesomePrint.defaults = {
 ## Setup
 #
 ### Option 1: Start a single-node cluster
-#     $ docker run -i -p 8108:8108 -v/tmp/typesense-server-data-1b/:/data -v`pwd`/typesense-server-peers:/typesense-server-peers typesense/typesense:0.12.rc9 --data-dir /data --api-key=xyz --search-only-api-key=abcd --listen-port 8108 --enable-cors
+#     $ docker run -i -p 8108:8108 -v/tmp/typesense-server-data-1b/:/data -v`pwd`/typesense-server-peers:/typesense-server-peers typesense/typesense:0.12.1.rc1 --data-dir /data --api-key=xyz --listen-port 8108 --enable-cors
 #
 ### Option 2: Start a 3-node cluster
 #
@@ -19,13 +19,13 @@ AwesomePrint.defaults = {
 #   $ echo '172.17.0.2:8107:8108,172.17.0.3:7107:7108,172.17.0.4:9107:9108' > `pwd`/typesense-server-peers
 #
 # Start node 1:
-#   $ docker run -i -p 8108:8108 -p 8107:8107 -v/tmp/typesense-server-data-1b/:/data -v`pwd`/typesense-server-peers:/typesense-server-peers typesense/typesense:0.12.rc9 --data-dir /data --api-key=xyz --search-only-api-key=abcd --listen-port 8108 --peering-port 8107 --enable-cors --nodes=/typesense-server-peers
+#   $ docker run -i -p 8108:8108 -p 8107:8107 -v/tmp/typesense-server-data-1b/:/data -v`pwd`/typesense-server-peers:/typesense-server-peers typesense/typesense:0.12.1.rc1 --data-dir /data --api-key=xyz --listen-port 8108 --peering-port 8107 --enable-cors --nodes=/typesense-server-peers
 #
 # Start node 2:
-#   $ docker run -i -p 7108:7108 -p 7107:7107 -v/tmp/.typesense-server-data-2b/:/data -v`pwd`/typesense-server-peers:/typesense-server-peers typesense/typesense:0.12.rc9 --data-dir /data --api-key=xyz --search-only-api-key=abcd --listen-port 7108 --peering-port 7107 --enable-cors --nodes=/typesense-server-peers
+#   $ docker run -i -p 7108:7108 -p 7107:7107 -v/tmp/.typesense-server-data-2b/:/data -v`pwd`/typesense-server-peers:/typesense-server-peers typesense/typesense:0.12.1.rc1 --data-dir /data --api-key=xyz --listen-port 7108 --peering-port 7107 --enable-cors --nodes=/typesense-server-peers
 #
 # Start node 3:
-#   $ docker run -i -p 9108:9108 -p 9107:9107 -v/tmp/.typesense-server-data-3b/:/data -v`pwd`/typesense-server-peers:/typesense-server-peers typesense/typesense:0.12.rc9 --data-dir /data --api-key=xyz --search-only-api-key=abcd --listen-port 9108 --peering-port 9107 --enable-cors --nodes=/typesense-server-peers
+#   $ docker run -i -p 9108:9108 -p 9107:9107 -v/tmp/.typesense-server-data-3b/:/data -v`pwd`/typesense-server-peers:/typesense-server-peers typesense/typesense:0.12.1.rc1 --data-dir /data --api-key=xyz --listen-port 9108 --peering-port 9107 --enable-cors --nodes=/typesense-server-peers
 #
 # Note: Be sure to add `--license-key=<>` at the end when starting a Typesense Premium server
 

data/examples/keys.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+##
+# These examples walk you through operations to manage API Keys
+
+require_relative './client_initialization'
+
+# Let's setup some test data for this example
+schema = {
+  'name' => 'users',
+  'fields' => [
+    {
+      'name' => 'company_id',
+      'type' => 'int32',
+      'facet' => false
+    },
+    {
+      'name' => 'user_name',
+      'type' => 'string',
+      'facet' => false
+    },
+    {
+      'name' => 'login_count',
+      'type' => 'int32',
+      'facet' => false
+    },
+    {
+      'name' => 'country',
+      'type' => 'string',
+      'facet' => true
+    }
+  ],
+  'default_sorting_field' => 'company_id'
+}
+
+# We have four users, belonging to two companies: 124 and 126
+documents = [
+  {
+    'company_id' => 124,
+    'user_name' => 'Hilary Bradford',
+    'login_count' => 10,
+    'country' => 'USA'
+  },
+  {
+    'company_id' => 124,
+    'user_name' => 'Nile Carty',
+    'login_count' => 100,
+    'country' => 'USA'
+  },
+  {
+    'company_id' => 126,
+    'user_name' => 'Tahlia Maxwell',
+    'login_count' => 1,
+    'country' => 'France'
+  },
+  {
+    'company_id' => 126,
+    'user_name' => 'Karl Roy',
+    'login_count' => 2,
+    'country' => 'Germany'
+  }
+]
+
+# Delete if the collection already exists from a previous example run
+begin
+  @typesense.collections['users'].delete
+rescue Typesense::Error::ObjectNotFound
+end
+
+# create a collection
+@typesense.collections.create(schema)
+
+# Index documents
+documents.each do |document|
+  @typesense.collections['users'].documents.create(document)
+end
+
+# Generate an API key and restrict it to only allow searches
+# You want to use this API Key in the browser instead of the master API Key
+unscoped_search_only_api_key_response = @typesense.keys.create({
+                                                                 'description' => 'Search-only key.',
+                                                                 'actions' => ['documents:search'],
+                                                                 'collections' => ['*']
+                                                               })
+ap unscoped_search_only_api_key_response
+
+# Save the key returned, since this will be the only time the full API Key is returned, for security purposes
+unscoped_search_only_api_key = unscoped_search_only_api_key_response['value']
+
+# Side note: you can also retrieve metadata of API keys using the ID returned in the above response
+unscoped_search_only_api_key_response = @typesense.keys[unscoped_search_only_api_key_response['id']].retrieve
+ap unscoped_search_only_api_key_response
+
+# We'll now use this search-only API key to generate a scoped search API key that can only access documents that have company_id:124
+#  This is useful when you store multi-tenant data in a single Typesense server, but you only want
+#  a particular tenant to access their own data. You'd generate one scoped search key per tenant.
+#  IMPORTANT: scoped search keys should only be generated *server-side*, so as to not leak the unscoped main search key to clients
+scoped_search_only_api_key = @typesense.keys.generate_scoped_search_key(unscoped_search_only_api_key, { 'filter_by': 'company_id:124' })
+ap "scoped_search_only_api_key: #{scoped_search_only_api_key}"
+
+# Now let's search the data using the scoped API Key for company_id:124
+# You can do searches with this scoped_search_only_api_key from the server-side or client-side
+scoped_typesense_client = Typesense::Client.new({
+                                                  'nodes': [{
+                                                    'host': 'localhost',
+                                                    'port': '8108',
+                                                    'protocol': 'http'
+                                                  }],
+                                                  'api_key': scoped_search_only_api_key
+                                                })
+
+search_results = scoped_typesense_client.collections['users'].documents.search({
+                                                                                 'q' => 'Hilary',
+                                                                                 'query_by' => 'user_name'
+                                                                               })
+ap search_results
+
+# Search for a user that exists, but is outside the current key's scope
+search_results = scoped_typesense_client.collections['users'].documents.search({
+                                                                                 'q': 'Maxwell',
+                                                                                 'query_by': 'user_name'
+                                                                               })
+ap search_results # Will return empty result set
+
+# Now let's delete the unscoped_search_only_api_key. You'd want to do this when you need to rotate keys for example.
+results = @typesense.keys[unscoped_search_only_api_key_response['id']].delete
+ap results

data/lib/typesense.rb

@@ -15,5 +15,7 @@ require_relative 'typesense/overrides'
 require_relative 'typesense/override'
 require_relative 'typesense/aliases'
 require_relative 'typesense/alias'
+require_relative 'typesense/keys'
+require_relative 'typesense/key'
 require_relative 'typesense/debug'
 require_relative 'typesense/error'

data/lib/typesense/client.rb

@@ -5,6 +5,7 @@ module Typesense
     attr_reader :configuration
     attr_reader :collections
     attr_reader :aliases
+    attr_reader :keys
     attr_reader :debug
 
     def initialize(options = {})
@@ -12,6 +13,7 @@ module Typesense
       @api_call = ApiCall.new(@configuration)
       @collections = Collections.new(@api_call)
       @aliases = Aliases.new(@api_call)
+      @keys = Keys.new(@api_call)
       @debug = Debug.new(@api_call)
     end
   end

data/lib/typesense/key.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Typesense
+  class Key
+    def initialize(id, api_call)
+      @id = id
+      @api_call = api_call
+    end
+
+    def retrieve
+      @api_call.get(endpoint_path)
+    end
+
+    def delete
+      @api_call.delete(endpoint_path)
+    end
+
+    private
+
+    def endpoint_path
+      "#{Keys::RESOURCE_PATH}/#{@id}"
+    end
+  end
+end

data/lib/typesense/keys.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module Typesense
+  class Keys
+    RESOURCE_PATH = '/keys'
+
+    def initialize(api_call)
+      @api_call = api_call
+      @keys = {}
+    end
+
+    def create(parameters)
+      @api_call.post(RESOURCE_PATH, parameters)
+    end
+
+    def retrieve
+      @api_call.get(RESOURCE_PATH)
+    end
+
+    def generate_scoped_search_key(search_key, parameters)
+      parameters_json = JSON.dump(parameters)
+      digest = Base64.encode64(OpenSSL::HMAC.digest('sha256', search_key, parameters_json)).gsub("\n", '')
+      key_prefix = search_key[0...4]
+      raw_scoped_key = "#{digest}#{key_prefix}#{parameters_json}"
+      Base64.encode64(raw_scoped_key).gsub("\n", '')
+    end
+
+    def [](id)
+      @keys[id] ||= Key.new(id, @api_call)
+    end
+  end
+end

data/lib/typesense/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Typesense
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: typesense
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Typesense, Inc.
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-05-23 00:00:00.000000000 Z
+date: 2020-05-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: awesome_print
@@ -229,6 +229,7 @@ files:
 - examples/aliases.rb
 - examples/client_initialization.rb
 - examples/collections_and_documents.rb
+- examples/keys.rb
 - examples/overrides.rb
 - examples/search.rb
 - lib/typesense.rb
@@ -243,6 +244,8 @@ files:
 - lib/typesense/document.rb
 - lib/typesense/documents.rb
 - lib/typesense/error.rb
+- lib/typesense/key.rb
+- lib/typesense/keys.rb
 - lib/typesense/override.rb
 - lib/typesense/overrides.rb
 - lib/typesense/version.rb