google-cloud-firestore 0.22.0 → 0.23.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 (43) hide show
  1. checksums.yaml +4 -4
  2. data/.yardopts +1 -0
  3. data/README.md +8 -8
  4. data/lib/google-cloud-firestore.rb +1 -1
  5. data/lib/google/cloud/firestore.rb +46 -0
  6. data/lib/google/cloud/firestore/batch.rb +1 -1
  7. data/lib/google/cloud/firestore/client.rb +18 -13
  8. data/lib/google/cloud/firestore/convert.rb +78 -35
  9. data/lib/google/cloud/firestore/credentials.rb +2 -12
  10. data/lib/google/cloud/firestore/document_change.rb +124 -0
  11. data/lib/google/cloud/firestore/document_listener.rb +125 -0
  12. data/lib/google/cloud/firestore/document_reference.rb +35 -0
  13. data/lib/google/cloud/firestore/document_snapshot.rb +91 -9
  14. data/lib/google/cloud/firestore/field_path.rb +23 -13
  15. data/lib/google/cloud/firestore/query.rb +513 -69
  16. data/lib/google/cloud/firestore/query_listener.rb +118 -0
  17. data/lib/google/cloud/firestore/query_snapshot.rb +121 -0
  18. data/lib/google/cloud/firestore/service.rb +8 -0
  19. data/lib/google/cloud/firestore/transaction.rb +2 -2
  20. data/lib/google/cloud/firestore/v1beta1.rb +62 -37
  21. data/lib/google/cloud/firestore/v1beta1/credentials.rb +41 -0
  22. data/lib/google/cloud/firestore/v1beta1/doc/google/firestore/v1beta1/common.rb +1 -1
  23. data/lib/google/cloud/firestore/v1beta1/doc/google/firestore/v1beta1/document.rb +5 -4
  24. data/lib/google/cloud/firestore/v1beta1/doc/google/firestore/v1beta1/firestore.rb +1 -12
  25. data/lib/google/cloud/firestore/v1beta1/doc/google/firestore/v1beta1/query.rb +4 -1
  26. data/lib/google/cloud/firestore/v1beta1/doc/google/firestore/v1beta1/write.rb +37 -8
  27. data/lib/google/cloud/firestore/v1beta1/doc/google/protobuf/any.rb +1 -1
  28. data/lib/google/cloud/firestore/v1beta1/doc/google/protobuf/empty.rb +28 -0
  29. data/lib/google/cloud/firestore/v1beta1/doc/google/protobuf/timestamp.rb +1 -1
  30. data/lib/google/cloud/firestore/v1beta1/doc/google/protobuf/wrappers.rb +1 -1
  31. data/lib/google/cloud/firestore/v1beta1/doc/google/rpc/status.rb +1 -1
  32. data/lib/google/cloud/firestore/v1beta1/firestore_client.rb +124 -56
  33. data/lib/google/cloud/firestore/v1beta1/firestore_client_config.json +2 -2
  34. data/lib/google/cloud/firestore/version.rb +1 -1
  35. data/lib/google/cloud/firestore/watch/enumerator_queue.rb +47 -0
  36. data/lib/google/cloud/firestore/watch/inventory.rb +280 -0
  37. data/lib/google/cloud/firestore/watch/listener.rb +298 -0
  38. data/lib/google/cloud/firestore/watch/order.rb +98 -0
  39. data/lib/google/firestore/v1beta1/firestore_services_pb.rb +2 -4
  40. data/lib/google/firestore/v1beta1/query_pb.rb +1 -0
  41. data/lib/google/firestore/v1beta1/write_pb.rb +2 -0
  42. metadata +40 -3
  43. data/lib/google/cloud/firestore/v1beta1/doc/overview.rb +0 -53
@@ -0,0 +1,118 @@
1
+ # Copyright 2018 Google LLC
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # https://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+
16
+ require "google/cloud/firestore/watch/listener"
17
+
18
+ module Google
19
+ module Cloud
20
+ module Firestore
21
+ ##
22
+ # # QueryListener
23
+ #
24
+ # An ongoing listen operation on a query. This is returned by calling
25
+ # {Query#listen}.
26
+ #
27
+ # @example
28
+ # require "google/cloud/firestore"
29
+ #
30
+ # firestore = Google::Cloud::Firestore.new
31
+ #
32
+ # # Create a query
33
+ # query = firestore.col(:cities).order(:population, :desc)
34
+ #
35
+ # listener = query.listen do |snapshot|
36
+ # puts "The query snapshot has #{snapshot.docs.count} documents "
37
+ # puts "and has #{snapshot.changes.count} changes."
38
+ # end
39
+ #
40
+ # # When ready, stop the listen operation and close the stream.
41
+ # listener.stop
42
+ #
43
+ class QueryListener
44
+ ##
45
+ # @private
46
+ # Creates the watch stream and listener object.
47
+ def initialize query, &callback
48
+ @query = query
49
+ raise ArgumentError if @query.nil?
50
+
51
+ @callback = callback
52
+ raise ArgumentError if @callback.nil?
53
+
54
+ @listener = Watch::Listener.for_query query, &callback
55
+ end
56
+
57
+ ##
58
+ # @private
59
+ def start
60
+ @listener.start
61
+ self
62
+ end
63
+
64
+ ##
65
+ # Stops the client listening for changes.
66
+ #
67
+ # @example
68
+ # require "google/cloud/firestore"
69
+ #
70
+ # firestore = Google::Cloud::Firestore.new
71
+ #
72
+ # # Create a query
73
+ # query = firestore.col(:cities).order(:population, :desc)
74
+ #
75
+ # listener = query.listen do |snapshot|
76
+ # puts "The query snapshot has #{snapshot.docs.count} documents "
77
+ # puts "and has #{snapshot.changes.count} changes."
78
+ # end
79
+ #
80
+ # # When ready, stop the listen operation and close the stream.
81
+ # listener.stop
82
+ #
83
+ def stop
84
+ @listener.stop
85
+ end
86
+
87
+ ##
88
+ # Whether the client has stopped listening for changes.
89
+ #
90
+ # @example
91
+ # require "google/cloud/firestore"
92
+ #
93
+ # firestore = Google::Cloud::Firestore.new
94
+ #
95
+ # # Create a query
96
+ # query = firestore.col(:cities).order(:population, :desc)
97
+ #
98
+ # listener = query.listen do |snapshot|
99
+ # puts "The query snapshot has #{snapshot.docs.count} documents "
100
+ # puts "and has #{snapshot.changes.count} changes."
101
+ # end
102
+ #
103
+ # # Checks if the listener is stopped.
104
+ # listener.stopped? #=> false
105
+ #
106
+ # # When ready, stop the listen operation and close the stream.
107
+ # listener.stop
108
+ #
109
+ # # Checks if the listener is stopped.
110
+ # listener.stopped? #=> true
111
+ #
112
+ def stopped?
113
+ @listener.stopped?
114
+ end
115
+ end
116
+ end
117
+ end
118
+ end
@@ -0,0 +1,121 @@
1
+ # Copyright 2018 Google LLC
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # https://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+
16
+ require "google/cloud/firestore/v1beta1"
17
+ require "google/cloud/firestore/document_reference"
18
+ require "google/cloud/firestore/collection_reference"
19
+ require "google/cloud/firestore/convert"
20
+
21
+ module Google
22
+ module Cloud
23
+ module Firestore
24
+ ##
25
+ # # QuerySnapshot
26
+ #
27
+ # A query snapshot object is an immutable representation of query results,
28
+ # including chnages from the previous snapshot.
29
+ #
30
+ # See {Query#listen}.
31
+ #
32
+ # @example
33
+ # require "google/cloud/firestore"
34
+ #
35
+ # firestore = Google::Cloud::Firestore.new
36
+ #
37
+ # # Create a query
38
+ # query = firestore.col(:cities).order(:population, :desc)
39
+ #
40
+ # listener = query.listen do |snapshot|
41
+ # puts "The query snapshot has #{snapshot.docs.count} documents "
42
+ # puts "and has #{snapshot.changes.count} changes."
43
+ # end
44
+ #
45
+ # # When ready, stop the listen operation and close the stream.
46
+ # listener.stop
47
+ #
48
+ class QuerySnapshot
49
+ ##
50
+ # The query producing this snapshot.
51
+ #
52
+ # @return [Query] query.
53
+ #
54
+ def query
55
+ @query
56
+ end
57
+
58
+ ##
59
+ # The documents in the snapshot.
60
+ #
61
+ # @return [Array<DocumentSnapshot>] document snapshots.
62
+ #
63
+ def docs
64
+ @docs
65
+ end
66
+ alias documents docs
67
+
68
+ ##
69
+ # The document change objects for the query snapshot.
70
+ #
71
+ # @return [Array<DocumentChange>] document changes.
72
+ #
73
+ def changes
74
+ @changes
75
+ end
76
+ alias doc_changes changes
77
+ alias document_changes changes
78
+
79
+ ##
80
+ # Returns the number of documents in this query snapshot.
81
+ #
82
+ # @return [Integer] The number of documents.
83
+ #
84
+ def size
85
+ docs.size
86
+ end
87
+ alias count size
88
+
89
+ ##
90
+ # Determines whether query results exists.
91
+ #
92
+ # @return [Boolean] Whether query results exists.
93
+ #
94
+ def empty?
95
+ docs.empty?
96
+ end
97
+
98
+ ##
99
+ # The time at which the snapshot was read.
100
+ #
101
+ # @return [Time] The time at which the documents were read.
102
+ #
103
+ def read_at
104
+ @read_at
105
+ end
106
+ alias read_time read_at
107
+
108
+ ##
109
+ # @private New QuerySnapshot
110
+ def self.from_docs query, docs, changes, read_at
111
+ new.tap do |s|
112
+ s.instance_variable_set :@query, query
113
+ s.instance_variable_set :@docs, docs
114
+ s.instance_variable_set :@changes, changes
115
+ s.instance_variable_set :@read_at, read_at
116
+ end
117
+ end
118
+ end
119
+ end
120
+ end
121
+ end
@@ -91,6 +91,14 @@ module Google
91
91
  end
92
92
  end
93
93
 
94
+ def listen enum
95
+ options = call_options parent: database_path
96
+
97
+ execute do
98
+ firestore.listen enum, options: options
99
+ end
100
+ end
101
+
94
102
  def begin_transaction transaction_opt
95
103
  options = call_options parent: database_path
96
104
 
@@ -29,9 +29,9 @@ module Google
29
29
  # execute atomically at a single logical point in time.
30
30
  #
31
31
  # All changes are accumulated in memory until the block passed to
32
- # {Database#transaction} completes. Transactions will be automatically
32
+ # {Client#transaction} completes. Transactions will be automatically
33
33
  # retried when documents change before the transaction is committed. See
34
- # {Database#transaction}.
34
+ # {Client#transaction}.
35
35
  #
36
36
  # @example
37
37
  # require "google/cloud/firestore"
@@ -1,4 +1,4 @@
1
- # Copyright 2017 Google LLC
1
+ # Copyright 2018 Google LLC
2
2
  #
3
3
  # Licensed under the Apache License, Version 2.0 (the "License");
4
4
  # you may not use this file except in compliance with the License.
@@ -16,33 +16,59 @@ require "google/cloud/firestore/v1beta1/firestore_client"
16
16
 
17
17
  module Google
18
18
  module Cloud
19
- # rubocop:disable LineLength
20
-
21
- ##
22
- # # Ruby Client for Google Cloud Firestore API ([Beta](https://github.com/GoogleCloudPlatform/google-cloud-ruby#versioning))
23
- #
24
- # [Google Cloud Firestore API][Product Documentation]:
25
- #
26
- # - [Product Documentation][]
27
- #
28
- # ## Quick Start
29
- # In order to use this library, you first need to go through the following
30
- # steps:
31
- #
32
- # 1. [Select or create a Cloud Platform project.](https://console.cloud.google.com/project)
33
- # 2. [Enable the Google Cloud Firestore API.](https://console.cloud.google.com/apis/api/firestore)
34
- # 3. [Setup Authentication.](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud/master/guides/authentication)
35
- #
36
- # ### Next Steps
37
- # - Read the [Google Cloud Firestore API Product documentation][Product Documentation]
38
- # to learn more about the product and see How-to Guides.
39
- # - View this [repository's main README](https://github.com/GoogleCloudPlatform/google-cloud-ruby/blob/master/README.md)
40
- # to see the full list of Cloud APIs that we cover.
41
- #
42
- # [Product Documentation]: https://cloud.google.com/firestore
43
- #
44
- #
45
19
  module Firestore
20
+ # rubocop:disable LineLength
21
+
22
+ ##
23
+ # # Ruby Client for Google Cloud Firestore API ([Beta](https://github.com/GoogleCloudPlatform/google-cloud-ruby#versioning))
24
+ #
25
+ # [Google Cloud Firestore API][Product Documentation]:
26
+ #
27
+ # - [Product Documentation][]
28
+ #
29
+ # ## Quick Start
30
+ # In order to use this library, you first need to go through the following
31
+ # steps:
32
+ #
33
+ # 1. [Select or create a Cloud Platform project.](https://console.cloud.google.com/project)
34
+ # 2. [Enable billing for your project.](https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project)
35
+ # 3. [Enable the Google Cloud Firestore API.](https://console.cloud.google.com/apis/library/firestore.googleapis.com)
36
+ # 4. [Setup Authentication.](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud/master/guides/authentication)
37
+ #
38
+ # ### Next Steps
39
+ # - Read the [Google Cloud Firestore API Product documentation][Product Documentation]
40
+ # to learn more about the product and see How-to Guides.
41
+ # - View this [repository's main README](https://github.com/GoogleCloudPlatform/google-cloud-ruby/blob/master/README.md)
42
+ # to see the full list of Cloud APIs that we cover.
43
+ #
44
+ # [Product Documentation]: https://cloud.google.com/firestore
45
+ #
46
+ # ## Enabling Logging
47
+ #
48
+ # To enable logging for this library, set the logger for the underlying [gRPC](https://github.com/grpc/grpc/tree/master/src/ruby) library.
49
+ # The logger that you set may be a Ruby stdlib [`Logger`](https://ruby-doc.org/stdlib-2.5.0/libdoc/logger/rdoc/Logger.html) as shown below,
50
+ # or a [`Google::Cloud::Logging::Logger`](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-logging/latest/google/cloud/logging/logger)
51
+ # that will write logs to [Stackdriver Logging](https://cloud.google.com/logging/). See [grpc/logconfig.rb](https://github.com/grpc/grpc/blob/master/src/ruby/lib/grpc/logconfig.rb)
52
+ # and the gRPC [spec_helper.rb](https://github.com/grpc/grpc/blob/master/src/ruby/spec/spec_helper.rb) for additional information.
53
+ #
54
+ # Configuring a Ruby stdlib logger:
55
+ #
56
+ # ```ruby
57
+ # require "logger"
58
+ #
59
+ # module MyLogger
60
+ # LOGGER = Logger.new $stderr, level: Logger::WARN
61
+ # def logger
62
+ # LOGGER
63
+ # end
64
+ # end
65
+ #
66
+ # # Define a gRPC module-level logger method before grpc/logconfig.rb loads.
67
+ # module GRPC
68
+ # extend MyLogger
69
+ # end
70
+ # ```
71
+ #
46
72
  module V1beta1
47
73
  # rubocop:enable LineLength
48
74
 
@@ -88,28 +114,27 @@ module Google
88
114
  # or the specified config is missing data points.
89
115
  # @param timeout [Numeric]
90
116
  # The default timeout, in seconds, for calls made through this client.
117
+ # @param metadata [Hash]
118
+ # Default metadata to be sent with each request. This can be overridden on a per call basis.
119
+ # @param exception_transformer [Proc]
120
+ # An optional proc that intercepts any exceptions raised during an API call to inject
121
+ # custom error handling.
91
122
  def self.new \
92
- service_path: nil,
93
- port: nil,
94
- channel: nil,
95
- chan_creds: nil,
96
- updater_proc: nil,
97
123
  credentials: nil,
98
124
  scopes: nil,
99
125
  client_config: nil,
100
126
  timeout: nil,
127
+ metadata: nil,
128
+ exception_transformer: nil,
101
129
  lib_name: nil,
102
130
  lib_version: nil
103
131
  kwargs = {
104
- service_path: service_path,
105
- port: port,
106
- channel: channel,
107
- chan_creds: chan_creds,
108
- updater_proc: updater_proc,
109
132
  credentials: credentials,
110
133
  scopes: scopes,
111
134
  client_config: client_config,
112
135
  timeout: timeout,
136
+ metadata: metadata,
137
+ exception_transformer: exception_transformer,
113
138
  lib_name: lib_name,
114
139
  lib_version: lib_version
115
140
  }.select { |_, v| v != nil }
@@ -0,0 +1,41 @@
1
+ # Copyright 2018 Google LLC
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # https://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+ require "googleauth"
16
+
17
+ module Google
18
+ module Cloud
19
+ module Firestore
20
+ module V1beta1
21
+ class Credentials < Google::Auth::Credentials
22
+ SCOPE = [
23
+ "https://www.googleapis.com/auth/cloud-platform",
24
+ "https://www.googleapis.com/auth/datastore"
25
+ ].freeze
26
+ PATH_ENV_VARS = %w(FIRESTORE_CREDENTIALS
27
+ FIRESTORE_KEYFILE
28
+ GOOGLE_CLOUD_CREDENTIALS
29
+ GOOGLE_CLOUD_KEYFILE
30
+ GCLOUD_KEYFILE)
31
+ JSON_ENV_VARS = %w(FIRESTORE_CREDENTIALS_JSON
32
+ FIRESTORE_KEYFILE_JSON
33
+ GOOGLE_CLOUD_CREDENTIALS_JSON
34
+ GOOGLE_CLOUD_KEYFILE_JSON
35
+ GCLOUD_KEYFILE_JSON)
36
+ DEFAULT_PATHS = ["~/.config/gcloud/application_default_credentials.json"]
37
+ end
38
+ end
39
+ end
40
+ end
41
+ end
@@ -1,4 +1,4 @@
1
- # Copyright 2017 Google LLC
1
+ # Copyright 2018 Google LLC
2
2
  #
3
3
  # Licensed under the Apache License, Version 2.0 (the "License");
4
4
  # you may not use this file except in compliance with the License.
@@ -1,4 +1,4 @@
1
- # Copyright 2017 Google LLC
1
+ # Copyright 2018 Google LLC
2
2
  #
3
3
  # Licensed under the Apache License, Version 2.0 (the "License");
4
4
  # you may not use this file except in compliance with the License.
@@ -29,7 +29,7 @@ module Google
29
29
  # The map keys represent field names.
30
30
  #
31
31
  # A simple field name contains only characters +a+ to +z+, +A+ to +Z+,
32
- # +0+ to +9+, or +_+, and must not start with +0+ to +9+ or +_+. For example,
32
+ # +0+ to +9+, or +_+, and must not start with +0+ to +9+. For example,
33
33
  # +foo_bar_17+.
34
34
  #
35
35
  # Field names matching the regular expression +__.*__+ are reserved. Reserved
@@ -59,7 +59,7 @@ module Google
59
59
  # @return [Google::Protobuf::Timestamp]
60
60
  # Output only. The time at which the document was last changed.
61
61
  #
62
- # This value is initally set to the +create_time+ then increases
62
+ # This value is initially set to the +create_time+ then increases
63
63
  # monotonically with each change to the document. It can also be
64
64
  # compared to values from other documents and the +read_time+ of a query.
65
65
  class Document; end
@@ -107,7 +107,8 @@ module Google
107
107
  # @return [Google::Firestore::V1beta1::ArrayValue]
108
108
  # An array value.
109
109
  #
110
- # Cannot contain another array value.
110
+ # Cannot directly contain another array value, though can contain an
111
+ # map which contains another array.
111
112
  # @!attribute [rw] map_value
112
113
  # @return [Google::Firestore::V1beta1::MapValue]
113
114
  # A map value.