elastic-enterprise-search 8.1.0 → 8.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bdfa7f9a297b7be12956c4afb18c566ef6362be6f80b7ddcdf210a63de35792b
-  data.tar.gz: c0ea8e919e929a7a9a03dd183198d7a29f49b95a9fc1e044fb6d1c4becf87adf
+  metadata.gz: 7c6b7f543ecfbb56fa72e108d6c86b8aad6c4185e14654ab1e32cc739054073e
+  data.tar.gz: b4692ff93dd20556e6dd8e758577c107c02c2ed0b114bab15aad094ace4dba37
 SHA512:
-  metadata.gz: 9bf7a70b4070b475c5929dee3dce93841db5150bd3502b1b22595ed037cc7f9fbb60e4ade158009af80059ee84f727c192663efd4e9913697bb5860110a327f5
-  data.tar.gz: 11ce05ae809478b90e8980b43b0c28fdfa33d79bb3d398fcf832d1bdb25c7495600cde089bb9d448d3a39599e17484c59bce1704f8f4f0fc5fc362eb2215ce37
+  metadata.gz: 428fc9ca35fcf144bf83e8ed51d71901f5faf6f8b933c6c5118d95af3aea859b14307c7473b891f49538890f127bfcc5c7980c04531c93ae7f5b22f99a056b72
+  data.tar.gz: 2dde8ce3996c9a6b0ee7e5fef81000ea9397c5c4c1ae0b54e3b61b8fb604508c1727cf61cf4a6ee87c86090e088e8d19e2a02effec877e637e76af74724109e6

data/docs/guide/connecting.asciidoc

@@ -1,7 +1,6 @@
 [[connecting]]
 == Connecting
 
-
 This page contains the information you need to connect and use the Client with Elastic Enterprise Search.
 
 **On this page**

data/docs/guide/overview.asciidoc

@@ -14,6 +14,7 @@ For **Elastic Enterprise Search 7.0** and later, use the major version 7 (`7.x.y
 
 [discrete]
 === HTTP Library
+
 This library uses https://github.com/elastic/elastic-transport-ruby[elastic-transport], the low-level Ruby client for connecting to an Elastic clusters - also used in the official https://github.com/elastic/elasticsearch-ruby[Elasticsearch Ruby Client]. It uses https://rubygems.org/gems/faraday[Faraday], which supports several https://lostisland.github.io/faraday/adapters/[adapters] and will use `Net::HTTP` by default. For optimal performance with the Enterprise Search API, we suggest using an HTTP library which supports persistent ("keep-alive") connections. For the standard Ruby implementation, this could be https://github.com/drbrain/net-http-persistent[Net::HTTP::Persistent], https://github.com/toland/patron[patron] or https://github.com/typhoeus/typhoeus[Typhoeus]. For JRuby, https://github.com/cheald/manticore[Manticore] is a great option as well. Require the library for the adapter in your code and then pass in the `:adapter` parameter to the client when you initialize it:
 
 [source,ruby]
@@ -38,7 +39,7 @@ If you don't specify a host and port, the client will default to `http://localho
 [discrete]
 === Logging
 
-You can enable logging with the default logger by passing `log: true` as a parameter to the client's initializer, or pass in a Logger object with the `:logger` parameter:
+You can enable logging with the default logger by passing `log: true` as a parameter to the client's initializer, or pass in a Logger object with the `:logger` parameter, any confoming logger implementation:
 
 [source,rb]
 ----------------------------
@@ -46,6 +47,34 @@ logger = MyLogger.new
 client = Elastic::EnterpriseSearch::Client.new(logger: logger)
 ----------------------------
 
+To trace requests and responses in the _Curl_ format, set the `trace` argument:
+
+[source,rb]
+----------------------------
+> client = Elastic::EnterpriseSearch::Client.new(trace: true)
+> client.health                                                                                                                                                                                         
+curl -X GET -H 'x-elastic-client-meta: ent=8.3.0,rb=3.1.2,t=8.0.1,fd=1.10.0,nh=0.2.0, User-Agent: elastic-transport-ruby/8.0.1 (RUBY_VERSION: 3.1.2; linux x86_64; Faraday v1.10.0), Content-Type: application/json
+' 'http://localhost:9200/api/ent/v1/internal/health/?pretty'                                                                                                                                                       
+                                                                                                                                                                                                                   
+# 2022-05-23T08:39:09+01:00 [200] (0.049s)                                                                                                                                                                         
+#                                                                                                                                                                                                                  
+# {"name":"5b8067bf95fb", ...
+ =>                                                                                                                                                                                                                
+#<Elastic::API::Response:0x00007f9096e15f90                                                                                                                                                                        
+ @response=                                                                                                                                                                                                        
+  #<Elastic::Transport::Transport::Response:0x00007f9096e160a8                                                                                                                                                     
+   @body=                                                                                                                                                                                                          
+    {"name"=>"5b8067bf95fb",
+    ...
+----------------------------
+
+This will use the `elastic-transport` default logger. But you can pass in a custom logger with:
+
+[source,rb]
+----------------------------
+client = Elastic::EnterpriseSearch::Client.new(tracer: my_tracer)
+----------------------------
+
 [discrete]
 === License
 

data/docs/guide/release_notes/80.asciidoc

@@ -1,4 +1,15 @@
 [[release_notes_80]]
+=== 8.0 Release notes
+
+[discrete]
+[[release_notes_801]]
+=== 8.0.1 Release notes
+
+- Adds tracer parameters to enable tracing in elastic-transport. See https://www.elastic.co/guide/en/enterprise-search-clients/ruby/current/overview.html#_logging[logging] for more information.
+- Updates Workplace Search OAuth implementation. See https://www.elastic.co/guide/en/enterprise-search-clients/ruby/current/workplace-search-api.html#ws-oauth-authentication[OAuth Authentication] for changes in the OAuth process.
+
+[discrete]
+[[release_notes_800]]
 === 8.0.0 Release notes
 
 [discrete]

data/docs/guide/release_notes/81.asciidoc

@@ -1,4 +1,15 @@
 [[release_notes_81]]
+=== 8.1 Release notes
+
+[discrete]
+[[release_notes_811]]
+=== 8.1.1 Release notes
+
+- Adds tracer parameters to enable tracing in elastic-transport. See https://www.elastic.co/guide/en/enterprise-search-clients/ruby/current/overview.html#_logging[logging] for more information.
+- Updates Workplace Search OAuth implementation. See https://www.elastic.co/guide/en/enterprise-search-clients/ruby/current/workplace-search-api.html#ws-oauth-authentication[OAuth Authentication] for changes in the OAuth process.
+
+[discrete]
+[[release_notes_810]]
 === 8.1.0 Release notes
 
 [discrete]

data/docs/guide/workplace-search-api.asciidoc

@@ -76,22 +76,42 @@ client.delete_documents_by_query(content_source_id, query: query)
 [[ws-oauth-authentication]]
 === OAuth Authentication
 
-You need to configure the OAuth Application for Search in order to use the Workplace Search client's `search` and `create_analytics` endpoints. You need to follow the steps in https://www.elastic.co/guide/en/workplace-search/current/building-custom-search-workplace-search.html#configuring-search-oauth[Configuring the OAuth Application for Search] to retrieve the credentials: Client ID and Client Secret to request access tokens from the authentication server.
+You need to configure the OAuth Application for Search in order to use the Workplace Search client's `search` and `create_analytics` endpoints. You need to follow the steps in https://www.elastic.co/guide/en/workplace-search/current/building-custom-search-workplace-search.html#configuring-search-oauth[Configuring the OAuth Application for Search] to retrieve the credentials: **Client ID** and **Client Secret** to request access tokens from the authentication server.
+
+The client implements https://www.elastic.co/guide/en/workplace-search/current/building-custom-search-workplace-search.html#authenticating-search-user-confidential[Authenticating Users with a Confidential OAuth Flow]. It provides a helper to obtain the autorization URL directly from the client once you've set the necessary values.
+
+The authorization endpoint is hosted by your Kibana deployment, so you need to provide the client with the https://www.elastic.co/guide/en/enterprise-search/current/endpoints-ref.html#kibana-base-url[base URL of your Kibana instance]. You can do this when you initialize the client:
+
+[source,rb]
+----------------------------
+client = Elastic::EnterpriseSearch::WorkplaceSearch::Client.new(http_auth: <access_token>, kibana_url: <kibana_url>)
+----------------------------
+
+Or you can set in an existing client:
 
 [source,rb]
 ----------------------------
 client = Elastic::EnterpriseSearch::WorkplaceSearch::Client.new(http_auth: <access_token>)
+client.kibana_url = <kibana_url>
+----------------------------
 
+Once you've instantiated a client and the base URL of your Kibana instance is set, you can get the URL for authorization like so:
+[source,rb]
+----------------------------
+# You get the values for client_id and client_secret when configuring the OAuth Application:
 client_id = <client_id>
 client_secret = <client_secret>
 redirect_uri = <redirect_uri>
 
 # Get the authorization URL:
 client.authorization_url(client_id, redirect_uri)
-> https://host:port/ws/oauth/authorize?response_type=code&client_id=client_id&redirect_uri=https%3A%2F%2Flocalhost%3A3002
+> https://kibana_url/app/enterprise_search/workplace_search/p/oauth/authorize?response_type=code&client_id=client_id&redirect_uri=https%3A%2F%2Flocalhost%3A3002
+
 ----------------------------
 
-Open the URL to authorize your application. Successful authorization redirects the user in accordance to the redirect URI provided (and configured for the application). The application server must now request for an access_token, which is generated by Workplace Search using the oauth/token endpoint, using the Client ID and Client Secret.
+Open the URL to authorize your application. Successful authorization redirects the user in accordance to the redirect URI provided (and configured for the application).
+
+The application server must now request for an `access_token`, which is generated by Workplace Search using the `oauth/token` endpoint, using the **Client ID** and **Client Secret**.
 
 [source,rb]
 ----------------------------
@@ -100,7 +120,7 @@ authorization_code = '<paste code from redirect>'
 access_token = client.request_access_token(client_id, client_secret, authorization_code, redirect_uri)
 
 # The access_token can now be used to issue a search request:
-client.search(body: {query: 'search query'}, access_token: access_token)
+client.search(body: { query: 'search query' }, access_token: access_token)
 ----------------------------
 
 See https://www.elastic.co/guide/en/workplace-search/current/workplace-search-search-api.html#search-api-overview[Search API Overview] for more search parameters.

data/lib/elastic/enterprise-search/client.rb

@@ -58,6 +58,8 @@ module Elastic
       # @option options [String] :proxy url of proxy to use, ex: "http://localhost:8888"
       # @option options [Boolean] :log Use the default logger (disabled by default)
       # @option arguments [Object] :logger An instance of a Logger-compatible object
+      # @option arguments [Boolean] :trace Use the default tracer (disabled by default)
+      # @option arguments [Object] :tracer An instance of a Logger-compatible object
       # @option arguments [Symbol] :adapter A specific adapter for Faraday (e.g. `:patron`)
       # @option enable_meta_header [Boolean] :enable_meta_header Enable sending the meta data header to Cloud.
       #                                                          (Default: true)
@@ -77,7 +79,9 @@ module Elastic
             transport_options: {
               request: { open_timeout: open_timeout }
             },
-            enable_meta_header: @options[:enable_meta_header] || true
+            enable_meta_header: @options[:enable_meta_header] || true,
+            trace: trace,
+            tracer: tracer
           )
       end
 
@@ -109,6 +113,14 @@ module Elastic
         @options[:adapter]
       end
 
+      def tracer
+        @options[:tracer]
+      end
+
+      def trace
+        @options[:trace]
+      end
+
       def host
         return DEFAULT_HOST unless @options[:host]
 

data/lib/elastic/enterprise-search/version.rb

@@ -19,6 +19,6 @@
 
 module Elastic
   module EnterpriseSearch
-    VERSION = '8.1.0'
+    VERSION = '8.1.1'
   end
 end

data/lib/elastic/workplace-search/workplace_search.rb

@@ -27,12 +27,17 @@ module Elastic
         include Elastic::EnterpriseSearch::WorkplaceSearch::Actions
         include Elastic::EnterpriseSearch::Utils
 
+        attr_accessor :kibana_url
+
         # Create a new Elastic::EnterpriseSearch::WorkplaceSearch::Client client
         #
         # @param options [Hash] a hash of configuration options
         # @option options [String] :access_token the access token for workplace search
         # @option options [String] :endpoint the endpoint Workplace Search
+        # @option options [String] :kibana_url The base URL of your Kibana instance
+        #
         def initialize(options = {})
+          @kibana_url = options[:kibana_url]
           super(options)
         end
 
@@ -45,9 +50,11 @@ module Elastic
         end
 
         def authorization_url(client_id, redirect_uri)
+          raise ArgumentError, 'kibana_url The base URL of your Kibana instance must be set in the client' unless kibana_url
+
           [
-            host,
-            '/ws/oauth/authorize?',
+            kibana_url,
+            '/app/enterprise_search/workplace_search/p/oauth/authorize?',
             'response_type=code&',
             "client_id=#{client_id}&",
             "redirect_uri=#{CGI.escape(redirect_uri)}"

data/spec/workplace-search/client_spec.rb

@@ -91,10 +91,18 @@ describe Elastic::EnterpriseSearch::WorkplaceSearch::Client do
   context 'OAuth' do
     let(:client) { Elastic::EnterpriseSearch::WorkplaceSearch::Client.new(host: host) }
 
-    it 'generates an authorization url' do
-      authorization_url = 'http://localhost:3002/ws/oauth/authorize?response_type=code&client_id=client_id&redirect_uri=https%3A%2F%2Flocalhost%3A3002'
+    it 'generates an authorization url when kibana url has been set' do
+      client.kibana_url = 'http://localhost:5601'
+      authorization_url = "#{client.kibana_url}/app/enterprise_search/workplace_search/p/oauth/authorize?" \
+                          'response_type=code&client_id=client_id&redirect_uri=https%3A%2F%2Flocalhost%3A3002'
       expect(client.authorization_url('client_id', 'https://localhost:3002')).to eq authorization_url
     end
+
+    it 'raises an error when kibana url is not set' do
+      expect do
+        client.authorization_url('client_id', 'https://localhost:3002')
+      end.to raise_exception(ArgumentError)
+    end
   end
 
   context 'adapters' do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: elastic-enterprise-search
 version: !ruby/object:Gem::Version
-  version: 8.1.0
+  version: 8.1.1
 platform: ruby
 authors:
 - Fernando Briano
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-05-11 00:00:00.000000000 Z
+date: 2022-05-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: elastic-transport
@@ -414,7 +414,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.3
+rubygems_version: 3.3.7
 signing_key: 
 specification_version: 4
 summary: Official API client for Elastic Enterprise Search