gcloud 0.6.3 → 0.7.0

data/lib/gcloud/dns/zone/list.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2015 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "delegate"
 
 module Gcloud
@@ -52,8 +52,8 @@ module Gcloud
         end
 
         ##
-        # New Zones::List from a response object.
-        def self.from_response resp, conn #:nodoc:
+        # @private New Zones::List from a response object.
+        def self.from_response resp, conn
           zones = new(Array(resp.data["managedZones"]).map do |gapi_object|
             Zone.from_gapi gapi_object, conn
           end)

data/lib/gcloud/dns/zone/transaction.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2015 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,16 +12,18 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 module Gcloud
   module Dns
     class Zone
       ##
-      # = DNS Zone Transaction
+      # # DNS Zone Transaction
       #
-      # This object is used by Zone#update when passed a block. These methods
+      # This object is used by {Zone#update} when passed a block. These methods
       # are used to update the records that are sent to the Google Cloud DNS
       # API.
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -39,11 +40,12 @@ module Gcloud
       #   end
       #
       class Transaction
-        attr_reader :additions, :deletions #:nodoc:
+        # @private
+        attr_reader :additions, :deletions
 
         ##
-        # Creates a new transaction.
-        def initialize zone #:nodoc:
+        # @private Creates a new transaction.
+        def initialize zone
           @zone = zone
           @additions = []
           @deletions = []
@@ -52,27 +54,21 @@ module Gcloud
         ##
         # Adds a record to the Zone.
         #
-        # === Parameters
-        #
-        # +name+::
-        #   The owner of the record. For example: +example.com.+. (+String+)
-        # +type+::
-        #   The identifier of a {supported record
-        #   type}[https://cloud.google.com/dns/what-is-cloud-dns].
-        #   For example: +A+, +AAAA+, +CNAME+, +MX+, or +TXT+. (+String+)
-        # +ttl+::
-        #   The number of seconds that the record can be cached by resolvers.
-        #   (+Integer+)
-        # +data+::
-        #   The resource record data, as determined by +type+ and defined in
-        #   {RFC 1035 (section 5)}[http://tools.ietf.org/html/rfc1035#section-5]
-        #   and {RFC 1034 (section
-        #   3.6.1)}[http://tools.ietf.org/html/rfc1034#section-3.6.1]. For
-        #   example: +192.0.2.1+ or +example.com.+. (+String+ or +Array+ of
-        #   +String+)
-        #
-        # === Example
-        #
+        # @param [String] name The owner of the record. For example:
+        #   `example.com.`.
+        # @param [String] type The identifier of a [supported record
+        #   type](https://cloud.google.com/dns/what-is-cloud-dns).
+        #   For example: `A`, `AAAA`, `CNAME`, `MX`, or `TXT`.
+        # @param [Integer] ttl The number of seconds that the record can be
+        #   cached by resolvers.
+        # @param [String, Array<String>] data The resource record data, as
+        #   determined by `type` and defined in
+        #   [RFC 1035 (section 5)](http://tools.ietf.org/html/rfc1035#section-5)
+        #   and [RFC 1034 (section
+        #   3.6.1)](http://tools.ietf.org/html/rfc1034#section-3.6.1). For
+        #   example: `192.0.2.1` or `example.com.`.
+        #
+        # @example
         #   require "gcloud"
         #
         #   gcloud = Gcloud.new
@@ -90,17 +86,13 @@ module Gcloud
         # Removes records from the Zone. The records are looked up before they
         # are removed.
         #
-        # === Parameters
-        #
-        # +name+::
-        #   The owner of the record. For example: +example.com.+. (+String+)
-        # +type+::
-        #   The identifier of a {supported record
-        #   type}[https://cloud.google.com/dns/what-is-cloud-dns].
-        #   For example: +A+, +AAAA+, +CNAME+, +MX+, or +TXT+. (+String+)
-        #
-        # === Example
+        # @param [String] name The owner of the record. For example:
+        #   `example.com.`.
+        # @param [String] type The identifier of a [supported record
+        #   type](https://cloud.google.com/dns/what-is-cloud-dns).
+        #   For example: `A`, `AAAA`, `CNAME`, `MX`, or `TXT`.
         #
+        # @example
         #   require "gcloud"
         #
         #   gcloud = Gcloud.new
@@ -115,30 +107,24 @@ module Gcloud
         end
 
         ##
-        # Replaces existing records on the Zone. Records matching the +name+ and
-        # +type+ are replaced.
-        #
-        # === Parameters
-        #
-        # +name+::
-        #   The owner of the record. For example: +example.com.+. (+String+)
-        # +type+::
-        #   The identifier of a {supported record
-        #   type}[https://cloud.google.com/dns/what-is-cloud-dns].
-        #   For example: +A+, +AAAA+, +CNAME+, +MX+, or +TXT+. (+String+)
-        # +ttl+::
-        #   The number of seconds that the record can be cached by resolvers.
-        #   (+Integer+)
-        # +data+::
-        #   The resource record data, as determined by +type+ and defined in
-        #   {RFC 1035 (section 5)}[http://tools.ietf.org/html/rfc1035#section-5]
-        #   and {RFC 1034 (section
-        #   3.6.1)}[http://tools.ietf.org/html/rfc1034#section-3.6.1]. For
-        #   example: +192.0.2.1+ or +example.com.+. (+String+ or +Array+ of
-        #   +String+)
-        #
-        # === Example
-        #
+        # Replaces existing records on the Zone. Records matching the `name` and
+        # `type` are replaced.
+        #
+        # @param [String] name The owner of the record. For example:
+        #   `example.com.`.
+        # @param [String] type The identifier of a [supported record
+        #   type](https://cloud.google.com/dns/what-is-cloud-dns).
+        #   For example: `A`, `AAAA`, `CNAME`, `MX`, or `TXT`.
+        # @param [Integer] ttl The number of seconds that the record can be
+        #   cached by resolvers.
+        # @param [String, Array<String>] data The resource record data, as
+        #   determined by `type` and defined in
+        #   [RFC 1035 (section 5)](http://tools.ietf.org/html/rfc1035#section-5)
+        #   and [RFC 1034 (section
+        #   3.6.1)](http://tools.ietf.org/html/rfc1034#section-3.6.1). For
+        #   example: `192.0.2.1` or `example.com.`.
+        #
+        # @example
         #   require "gcloud"
         #
         #   gcloud = Gcloud.new
@@ -155,20 +141,18 @@ module Gcloud
         end
 
         ##
-        # Modifies records on the Zone. Records matching the +name+ and +type+
+        # Modifies records on the Zone. Records matching the `name` and `type`
         # are yielded to the block where they can be modified.
         #
-        # === Parameters
-        #
-        # +name+::
-        #   The owner of the record. For example: +example.com.+. (+String+)
-        # +type+::
-        #   The identifier of a {supported record
-        #   type}[https://cloud.google.com/dns/what-is-cloud-dns].
-        #   For example: +A+, +AAAA+, +CNAME+, +MX+, or +TXT+. (+String+)
-        #
-        # === Example
+        # @param [String] name The owner of the record. For example:
+        #   `example.com.`.
+        # @param [String] type The identifier of a [supported record
+        #   type](https://cloud.google.com/dns/what-is-cloud-dns).
+        #   For example: `A`, `AAAA`, `CNAME`, `MX`, or `TXT`.
+        # @yield [record] a block yielding each matching record
+        # @yieldparam [Record] record the record to be modified
         #
+        # @example
         #   require "gcloud"
         #
         #   gcloud = Gcloud.new

data/lib/gcloud/errors.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2015 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,11 +12,183 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-#--
-# Google Cloud Errors
+
 module Gcloud
   ##
   # Base Gcloud exception class.
   class Error < StandardError
+    ##
+    # The inner error object.
+    attr_reader :inner
+
+    ##
+    # Create a new error object.
+    def initialize message = nil, error = nil
+      super message
+      @inner = error
+    end
+
+    # @private Create a new error object.
+    def self.from_error error
+      klass_for(error).new error.message, error
+    end
+
+    # @private Identify the subclass for an error
+    def self.klass_for error
+      return self.class unless error.is_a? GRPC::BadStatus
+      # The gRPC status code 0 is for a successful response.
+      # So there is no error subclass for a 0 status code, use current class.
+      [self.class, CanceledError, UnknownError, InvalidArgumentError,
+       DeadlineExceededError, NotFoundError, AlreadyExistsError,
+       PermissionDeniedError, ResourceExhaustedError, FailedPreconditionError,
+       AbortedError, OutOfRangeError, UnimplementedError, InternalError,
+       UnavailableError, DataLossError, UnauthenticatedError
+      ][error.code] || self.class
+    end
+  end
+
+  ##
+  # Canceled indicates the operation was cancelled (typically by the caller).
+  class CanceledError < Error
+  end
+
+  ##
+  # Unknown error.  An example of where this error may be returned is
+  # if a Status value received from another address space belongs to
+  # an error-space that is not known in this address space.  Also
+  # errors raised by APIs that do not return enough error information
+  # may be converted to this error.
+  class UnknownError < Error
+  end
+
+  ##
+  # InvalidArgument indicates client specified an invalid argument.
+  # Note that this differs from FailedPrecondition. It indicates arguments
+  # that are problematic regardless of the state of the system
+  # (e.g., a malformed file name).
+  class InvalidArgumentError < Error
+  end
+
+  ##
+  # DeadlineExceeded means operation expired before completion.
+  # For operations that change the state of the system, this error may be
+  # returned even if the operation has completed successfully. For
+  # example, a successful response from a server could have been delayed
+  # long enough for the deadline to expire.
+  class DeadlineExceededError < Error
+  end
+
+  ##
+  # NotFound means some requested entity (e.g., file or directory) was
+  # not found.
+  class NotFoundError < Error
+  end
+
+  ##
+  # AlreadyExists means an attempt to create an entity failed because one
+  # already exists.
+  class AlreadyExistsError < Error
+  end
+
+  ##
+  # PermissionDenied indicates the caller does not have permission to
+  # execute the specified operation. It must not be used for rejections
+  # caused by exhausting some resource (use ResourceExhausted
+  # instead for those errors).  It must not be
+  # used if the caller cannot be identified (use Unauthenticated
+  # instead for those errors).
+  class PermissionDeniedError < Error
+  end
+
+  ##
+  # Unauthenticated indicates the request does not have valid
+  # authentication credentials for the operation.
+  class UnauthenticatedError < Error
+  end
+
+  ##
+  # ResourceExhausted indicates some resource has been exhausted, perhaps
+  # a per-user quota, or perhaps the entire file system is out of space.
+  class ResourceExhaustedError < Error
+  end
+
+  ##
+  # FailedPrecondition indicates operation was rejected because the
+  # system is not in a state required for the operation's execution.
+  # For example, directory to be deleted may be non-empty, an rmdir
+  # operation is applied to a non-directory, etc.
+  #
+  # A litmus test that may help a service implementor in deciding
+  # between FailedPrecondition, Aborted, and Unavailable:
+  #  (a) Use Unavailable if the client can retry just the failing call.
+  #  (b) Use Aborted if the client should retry at a higher-level
+  #      (e.g., restarting a read-modify-write sequence).
+  #  (c) Use FailedPrecondition if the client should not retry until
+  #      the system state has been explicitly fixed.  E.g., if an "rmdir"
+  #      fails because the directory is non-empty, FailedPrecondition
+  #      should be returned since the client should not retry unless
+  #      they have first fixed up the directory by deleting files from it.
+  #  (d) Use FailedPrecondition if the client performs conditional
+  #      REST Get/Update/Delete on a resource and the resource on the
+  #      server does not match the condition. E.g., conflicting
+  #      read-modify-write on the same resource.
+  class FailedPreconditionError < Error
+  end
+
+  ##
+  # Aborted indicates the operation was aborted, typically due to a
+  # concurrency issue like sequencer check failures, transaction aborts,
+  # etc.
+  #
+  # See litmus test above for deciding between FailedPrecondition,
+  # Aborted, and Unavailable.
+  class AbortedError < Error
+  end
+
+  ##
+  # OutOfRange means operation was attempted past the valid range.
+  # E.g., seeking or reading past end of file.
+  #
+  # Unlike InvalidArgument, this error indicates a problem that may
+  # be fixed if the system state changes. For example, a 32-bit file
+  # system will generate InvalidArgument if asked to read at an
+  # offset that is not in the range [0,2^32-1], but it will generate
+  # OutOfRange if asked to read from an offset past the current
+  # file size.
+  #
+  # There is a fair bit of overlap between FailedPrecondition and
+  # OutOfRange.  We recommend using OutOfRange (the more specific
+  # error) when it applies so that callers who are iterating through
+  # a space can easily look for an OutOfRange error to detect when
+  # they are done.
+  class OutOfRangeError < Error
+  end
+
+  ##
+  # Unimplemented indicates operation is not implemented or not
+  # supported/enabled in this service.
+  class UnimplementedError < Error
+  end
+
+  ##
+  # Internal errors.  Means some invariants expected by underlying
+  # system has been broken.  If you see one of these errors,
+  # something is very broken.
+  class InternalError < Error
+  end
+
+  ##
+  # Unavailable indicates the service is currently unavailable.
+  # This is a most likely a transient condition and may be corrected
+  # by retrying with a backoff.
+  #
+  # See litmus test above for deciding between FailedPrecondition,
+  # Aborted, and Unavailable.
+  class UnavailableError < Error
+  end
+
+  ##
+  # DataLoss indicates unrecoverable data loss or corruption.
+  class DataLossError < Error
   end
 end

data/lib/gcloud/gce.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2015 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,14 +12,14 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "faraday"
 
-#--
-# Google Cloud Compute Engine
 module Gcloud
   ##
+  # @private
   # Represents the Google Compute Engine environment.
-  module GCE #:nodoc:
+  module GCE
     CHECK_URI = "http://169.254.169.254"
     PROJECT_URI = "#{CHECK_URI}/computeMetadata/v1/project/project-id"
 

data/lib/gcloud/grpc_utils.rb

@@ -0,0 +1,76 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require "gcloud"
+require "google/protobuf/struct"
+
+module Gcloud
+  ##
+  # @private Conversion to/from GRPC objects.
+  module GRPCUtils
+    ##
+    # @private Convert a Hash to a Google::Protobuf::Struct.
+    def self.hash_to_struct hash
+      # TODO: ArgumentError if hash is not a Hash
+      Google::Protobuf::Struct.new fields:
+        Hash[hash.map { |k, v| [String(k), object_to_value(v)] }]
+    end
+
+    ##
+    # @private Convert a Google::Protobuf::Struct to a Hash.
+    def self.struct_to_hash struct
+      # TODO: ArgumentError if struct is not a Google::Protobuf::Struct
+      Hash[struct.fields.map { |k, v| [k, value_to_object(v)] }]
+    end
+
+    ##
+    # @private Convert a Google::Protobuf::Value to an Object.
+    def self.value_to_object value
+      # TODO: ArgumentError if struct is not a Google::Protobuf::Value
+      if value.null_value
+        nil
+      elsif value.number_value
+        value.number_value
+      elsif value.struct_value
+        struct_to_hash value.struct_value
+      elsif value.list_value
+        value.list_value.values.map { |v| value_to_object(v) }
+      elsif !value.bool_value.nil? # Make sure its a bool, not nil
+        value.bool_value
+      else
+        nil # just in case
+      end
+    end
+
+    ##
+    # @private Convert an Object to a Google::Protobuf::Value.
+    def self.object_to_value obj
+      case obj
+      when String then Google::Protobuf::Value.new string_value: obj
+      when Array then Google::Protobuf::ListValue.new(values:
+        obj.map { |o| object_to_value(o) })
+      when Hash then Google::Protobuf::Value.new struct_value:
+        hash_to_struct(obj)
+      when Numeric then Google::Protobuf::Value.new number_value: obj
+      when TrueClass then Google::Protobuf::Value.new bool_value: true
+      when FalseClass then Google::Protobuf::Value.new bool_value: false
+      when NilClass then Google::Protobuf::Value.new null_value: :NULL_VALUE
+      else
+        # We could raise ArgumentError here, or we could convert to a string...
+        Google::Protobuf::Value.new string_value: obj.to_s
+      end
+    end
+  end
+end