gcloud 0.1.1 → 0.2.0

data/lib/gcloud/datastore/dataset.rb

@@ -33,23 +33,24 @@ module Gcloud
     # Google Datastore. Gcloud::Datastore::Entity objects are created,
     # read, updated, and deleted by Gcloud::Datastore::Dataset.
     #
-    #   require "gcloud/datastore"
+    #   require "gcloud"
     #
-    #   dataset = Gcloud.datastore
+    #   gcloud = Gcloud.new
+    #   dataset = gcloud.datastore
     #
     #   query = Gcloud::Datastore::Query.new.kind("Task").
     #     where("completed", "=", true)
     #
     #   tasks = dataset.run query
     #
-    # See Gcloud.datastore
+    # See Gcloud#datastore
     class Dataset
       attr_accessor :connection #:nodoc:
 
       ##
       # Creates a new Dataset instance.
       #
-      # See Gcloud.datastore
+      # See Gcloud#datastore
       def initialize project, credentials #:nodoc:
         @connection = Connection.new project, credentials
       end
@@ -59,11 +60,12 @@ module Gcloud
       #
       # === Example
       #
-      #   require "gcloud/datastore"
+      #   require "gcloud"
       #
-      #   dataset = Gcloud.datastore "my-todo-project",
-      #                              "/path/to/keyfile.json"
+      #   gcloud = Gcloud.new "my-todo-project",
+      #                       "/path/to/keyfile.json"
       #
+      #   dataset = gcloud.datastore
       #   dataset.project #=> "my-todo-project"
       #
       def project
@@ -139,7 +141,7 @@ module Gcloud
       #
       # +key_or_kind+::
       #   A Key object or +kind+ string value. (+Key+ or +String+)
-      # +key_or_kind+::
+      # +id_or_name+::
       #   The Key's +id+ or +name+ value if a +kind+ was provided in the first
       #   parameter. (+Integer+ or +String+ or +nil+)
       #
@@ -179,7 +181,8 @@ module Gcloud
       #
       # === Example
       #
-      #   dataset = Gcloud.datastore
+      #   gcloud = Gcloud.new
+      #   dataset = gcloud.datastore
       #   key1 = Gcloud::Datastore::Key.new "Task", 123456
       #   key2 = Gcloud::Datastore::Key.new "Task", 987654
       #   tasks = dataset.find_all key1, key2
@@ -207,7 +210,8 @@ module Gcloud
       #
       # === Example
       #
-      #   dataset = Gcloud.datastore
+      #   gcloud = Gcloud.new
+      #   dataset = gcloud.datastore
       #   dataset.delete entity1, entity2
       #
       def delete *entities_or_keys
@@ -255,9 +259,10 @@ module Gcloud
       #
       # Runs the given block in a database transaction:
       #
-      #   require "gcloud/datastore"
+      #   require "gcloud"
       #
-      #   dataset = Gcloud.datastore
+      #   gcloud = Gcloud.new
+      #   dataset = gcloud.datastore
       #
       #   key = Gcloud::Datastore::Key.new "User", "heidi"
       #
@@ -274,9 +279,10 @@ module Gcloud
       #
       # Alternatively, if no block is given a Transaction object is returned:
       #
-      #   require "gcloud/datastore"
+      #   require "gcloud"
       #
-      #   dataset = Gcloud.datastore
+      #   gcloud = Gcloud.new
+      #   dataset = gcloud.datastore
       #
       #   key = Gcloud::Datastore::Key.new "User", "heidi"
       #

data/lib/gcloud/datastore/entity.rb

@@ -58,18 +58,20 @@ module Gcloud
       #
       # Properties can be retrieved with a string name:
       #
-      #   require "gcloud/datastore"
+      #   require "gcloud"
       #
-      #   dataset = Gcloud.datastore
-      #   user = datastore.find "User", "heidi"
+      #   gcloud = Gcloud.new
+      #   dataset = gcloud.datastore
+      #   user = dataset.find "User", "heidi"
       #   user["name"] #=> "Heidi Henderson"
       #
       # Or with a symbol name:
       #
-      #   require "gcloud/datastore"
+      #   require "gcloud"
       #
-      #   dataset = Gcloud.datastore
-      #   user = datastore.find "User", "heidi"
+      #   gcloud = Gcloud.new
+      #   dataset = gcloud.datastore
+      #   user = dataset.find "User", "heidi"
       #   user[:name] #=> "Heidi Henderson"
       #
       def [] prop_name
@@ -90,18 +92,20 @@ module Gcloud
       #
       # Properties can be set with a string name:
       #
-      #   require "gcloud/datastore"
+      #   require "gcloud"
       #
-      #   dataset = Gcloud.datastore
-      #   user = datastore.find "User", "heidi"
+      #   gcloud = Gcloud.new
+      #   dataset = gcloud.datastore
+      #   user = dataset.find "User", "heidi"
       #   user["name"] = "Heidi H. Henderson"
       #
       # Or with a symbol name:
       #
-      #   require "gcloud/datastore"
+      #   require "gcloud"
       #
-      #   dataset = Gcloud.datastore
-      #   user = datastore.find "User", "heidi"
+      #   gcloud = Gcloud.new
+      #   dataset = gcloud.datastore
+      #   user = dataset.find "User", "heidi"
       #   user[:name] = "Heidi H. Henderson"
       #
       def []= prop_name, prop_value
@@ -149,9 +153,10 @@ module Gcloud
       #
       # The Key can be set before the entity is saved.
       #
-      #   require "glcoud/datastore"
+      #   require "gcloud"
       #
-      #   dataset = Gcloud.datastore
+      #   gcloud = Gcloud.new
+      #   dataset = gcloud.datastore
       #   entity = Gcloud::Datastore::Entity.new
       #   entity.key = Gcloud::Datastore::Key.new "User"
       #   dataset.save entity
@@ -159,9 +164,10 @@ module Gcloud
       # Once the entity is saved, the key is frozen and immutable.
       # Trying to set a key when immutable will raise a +RuntimeError+.
       #
-      #   require "gcloud/datastore"
+      #   require "gcloud"
       #
-      #   dataset = Gcloud.datastore
+      #   gcloud = Gcloud.new
+      #   dataset = gcloud.datastore
       #   entity = dataset.find "User", "heidi"
       #   entity.persisted? #=> true
       #   entity.key = Gcloud::Datastore::Key.new "User" #=> RuntimeError
@@ -178,9 +184,10 @@ module Gcloud
       #
       # === Example
       #
-      #   require "gcloud/datastore"
+      #   require "gcloud"
       #
-      #   dataset = Gcloud.datastore
+      #   gcloud = Gcloud.new
+      #   dataset = gcloud.datastore
       #
       #   new_entity = Gcloud::Datastore::Entity.new
       #   new_entity.persisted? #=> false

data/lib/gcloud/datastore/key.rb

@@ -51,11 +51,12 @@ module Gcloud
       #
       # === Example
       #
-      #   require "glcoud/datastore"
+      #   require "gcloud"
       #
-      #   dataset = Gcloud.datastore "my-todo-project",
-      #                              "/path/to/keyfile.json"
+      #   gcloud = Gcloud.new "my-todo-project",
+      #                       "/path/to/keyfile.json"
       #
+      #   dataset = gcloud.datastore
       #   entity = dataset.find "User", "heidi"
       #   entity.key.dataset_id #=> "my-todo-project"
       #
@@ -70,11 +71,12 @@ module Gcloud
       #
       # === Example
       #
-      #   require "glcoud/datastore"
+      #   require "gcloud"
       #
-      #   dataset = Gcloud.datastore "my-todo-project",
-      #                              "/path/to/keyfile.json"
+      #   gcloud = Gcloud.new "my-todo-project",
+      #                       "/path/to/keyfile.json"
       #
+      #   dataset = gcloud.datastore
       #   entity = dataset.find "User", "heidi"
       #   entity.key.namespace #=> "ns~todo-project"
       #
@@ -188,9 +190,10 @@ module Gcloud
       #
       # === Example
       #
-      #   require "glcoud/datastore"
+      #   require "gcloud"
       #
-      #   dataset = Gcloud.datastore
+      #   gcloud = Gcloud.new
+      #   dataset = gcloud.datastore
       #
       #   user = dataset.find "User", "heidi"
       #   query = Gcloud::Datastore::Query.new

data/lib/gcloud/pubsub.rb

@@ -0,0 +1,375 @@
+#--
+# Copyright 2015 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 "gcloud/pubsub/project"
+
+#--
+# Google Cloud Pub/Sub
+module Gcloud
+  ##
+  # Creates a new object for connecting to the Pub/Sub service.
+  # Each call creates a new connection.
+  #
+  # === Parameters
+  #
+  # +project+::
+  #   Project identifier for the Pub/Sub service you are connecting to.
+  #   (+String+)
+  # +keyfile+::
+  #   Keyfile downloaded from Google Cloud. If file path the file must be
+  #   readable. (+String+ or +Hash+)
+  #
+  # === Returns
+  #
+  # Gcloud::Pubsub::Project
+  #
+  # === Example
+  #
+  #   require "gcloud/pubsub"
+  #
+  #   pubsub = Gcloud.pubsub
+  #
+  #   topic = pubsub.topic "my-topic"
+  #   topic.publish "task completed"
+  #
+  def self.pubsub project = nil, keyfile = nil
+    project ||= Gcloud::Pubsub::Project.default_project
+    if keyfile.nil?
+      credentials = Gcloud::Pubsub::Credentials.default
+    else
+      credentials = Gcloud::Pubsub::Credentials.new keyfile
+    end
+    Gcloud::Pubsub::Project.new project, credentials
+  end
+
+  ##
+  # = Google Cloud Pub/Sub
+  #
+  # Google Cloud Pub/Sub is designed to provide reliable, many-to-many,
+  # asynchronous messaging between applications. Publisher applications can
+  # send messages to a "topic" and other applications can subscribe to that
+  # topic to receive the messages. By decoupling senders and receivers, Google
+  # Cloud Pub/Sub allows developers to communicate between independently written
+  # applications.
+  #
+  # Gcloud's goal is to provide a API that is familiar and comfortable to
+  # Rubyists. Authentication is handled by Gcloud#pubsub. You can provide the
+  # project and credential information to connect to the Pub/Sub service, or if
+  # you are running on Google Compute Engine this configuration is taken care
+  # of for you.
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   pubsub = gcloud.pubsub
+  #
+  #   topic = pubsub.topic "my-topic"
+  #   topic.publish "task completed"
+  #
+  # To learn more about Pub/Sub, read the {Google Cloud Pub/Sub Overview
+  # }[https://cloud.google.com/pubsub/overview].
+  #
+  # == Retrieving Topics
+  #
+  # A Topic is a named resource to which messages are sent by publishers.
+  # A Topic is found by its name. (See Project#topic)
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   pubsub = gcloud.pubsub
+  #   topic = pubsub.topic "my-topic"
+  #
+  # == Creating a Topic
+  #
+  # A Topic is created from a Project. (See Project#create_topic)
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   pubsub = gcloud.pubsub
+  #   topic = pubsub.create_topic "my-topic"
+  #
+  # == Publishing Messages
+  #
+  # Messages are published to a topic. (See Topic#publish)
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   pubsub = gcloud.pubsub
+  #
+  #   topic = pubsub.topic "my-topic"
+  #   msg = topic.publish "new-message"
+  #
+  # Messages can also be published with attributes:
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   pubsub = gcloud.pubsub
+  #
+  #   topic = pubsub.topic "my-topic"
+  #   msg = topic.publish "new-message",
+  #                       foo: :bar,
+  #                       this: :that
+  #
+  # Multiple messages can be published at the same time by passing a block:
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   pubsub = gcloud.pubsub
+  #
+  #   topic = pubsub.topic "my-topic"
+  #   msgs = topic.publish do |batch|
+  #     batch.publish "new-message-1", foo: :bar
+  #     batch.publish "new-message-2", foo: :baz
+  #     batch.publish "new-message-3", foo: :bif
+  #   end
+  #
+  # == Retrieving Subscriptions
+  #
+  # A Subscription is a named resource representing the stream of messages from
+  # a single, specific Topic, to be delivered to the subscribing application.
+  # A Subscription is found by its name. (See Topic#subscription)
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   pubsub = gcloud.pubsub
+  #
+  #   topic = pubsub.topic "my-topic"
+  #   subscription = topic.subscription "my-topic-subscription"
+  #   puts subscription.name
+  #
+  # == Creating a Subscription
+  #
+  # A Subscription is created from a Topic. (See Topic#subscribe)
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   pubsub = gcloud.pubsub
+  #
+  #   topic = pubsub.topic "my-topic"
+  #   sub = topic.subscribe "my-topic-sub"
+  #   puts sub.name # => "my-topic-sub"
+  #
+  # The subscription can be created that specifies the number of seconds to
+  # wait to be acknowledged as well as an endpoint URL to push the messages to:
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   pubsub = gcloud.pubsub
+  #
+  #   topic = pubsub.topic "my-topic"
+  #   sub = topic.subscribe "my-topic-sub",
+  #                         deadline: 120,
+  #                         endpoint: "https://example.com/push"
+  #
+  # == Working Across Projects
+  #
+  # All calls to the Pub/Sub service use the same project and credentials
+  # provided to the Gcloud#pubsub method. However, it is common to reference
+  # topics or subscriptions in other projects, which can be achieved by using
+  # the +project+ option. The main credentials must have permissions to the
+  # topics and subscriptions in other projects.
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new # my-project-id
+  #   pubsub = gcloud.pubsub
+  #
+  #   # Get a topic in the current project
+  #   my_topic = pubsub.topic "my-topic"
+  #   my_topic.name #=> "projects/my-project-id/topics/my-topic"
+  #   # Get a topic in another project
+  #   other_topic = pubsub.topic "other-topic", project: "other-project-id"
+  #   other_topic.name #=> "projects/other-project-id/topics/other-topic"
+  #
+  # It is possible to create a subscription in the current project that pulls
+  # from a topic in another project:
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new # my-project-id
+  #   pubsub = gcloud.pubsub
+  #
+  #   # Get a topic in another project
+  #   topic = pubsub.topic "other-topic", project: "other-project-id"
+  #   # Create a subscription in the current project that pulls from
+  #   # the topic in another project
+  #   sub = topic.subscribe "my-sub"
+  #   sub.name #=> "projects/my-project-id/subscriptions/my-sub"
+  #   sub.topic.name #=> "projects/other-project-id/topics/other-topic"
+  #
+  # == Pulling Messages
+  #
+  # Messages are pulled from a Subscription. (See Subscription#pull)
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   pubsub = gcloud.pubsub
+  #
+  #   sub = pubsub.subscription "my-topic-sub"
+  #   msgs = sub.pull
+  #
+  # A maximum number of messages returned can also be specified:
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   pubsub = gcloud.pubsub
+  #
+  #   sub = pubsub.subscription "my-topic-sub", max: 10
+  #   msgs = sub.pull
+  #
+  # The request for messages can also block until messages are available.
+  # (See Subscription#wait_for_messages)
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   pubsub = gcloud.pubsub
+  #
+  #   sub = pubsub.subscription "my-topic-sub"
+  #   msgs = sub.wait_for_messages
+  #
+  # == Acknowledging a Message
+  #
+  # Messages that are received can be acknowledged in Pub/Sub, marking the
+  # message to be removed so it cannot be pulled again.
+  #
+  # A Message that can be acknowledged is called a ReceivedMessage.
+  # ReceivedMessages can be acknowledged one at a time:
+  # (See ReceivedMessage#acknowledge!)
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   pubsub = gcloud.pubsub
+  #
+  #   sub = pubsub.subscription "my-topic-sub"
+  #   sub.pull.each { |msg| msg.acknowledge! }
+  #
+  # Or, multiple messages can be acknowledged in a single API call:
+  # (See Subscription#acknowledge)
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   pubsub = gcloud.pubsub
+  #
+  #   sub = pubsub.subscription "my-topic-sub"
+  #   received_messages = sub.pull
+  #   sub.acknowledge received_messages
+  #
+  # == Modifying a Deadline
+  #
+  # A message must be acknowledged after it is pulled, or Pub/Sub will mark the
+  # message for redelivery. The message acknowledgement deadline can delayed if
+  # more time is needed. This will allow more time to process the message before
+  # the message is marked for redelivery. (See ReceivedMessage#delay!)
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   pubsub = gcloud.pubsub
+  #
+  #   sub = pubsub.subscription "my-topic-sub"
+  #   received_message = sub.pull.first
+  #   if received_message
+  #     puts received_message.message.data
+  #     # Delay for 2 minutes
+  #     received_message.delay! 120
+  #   end
+  #
+  # The message can also be made available for immediate redelivery:
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   pubsub = gcloud.pubsub
+  #
+  #   sub = pubsub.subscription "my-topic-sub"
+  #   received_message = sub.pull.first
+  #   if received_message
+  #     puts received_message.message.data
+  #     # Mark for redelivery by setting the deadline to now
+  #     received_message.delay! 0
+  #   end
+  #
+  # Multiple messages can be delayed or made available for immediate redelivery:
+  # (See Subscription#delay)
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   pubsub = gcloud.pubsub
+  #
+  #   sub = pubsub.subscription "my-topic-sub"
+  #   received_messages = sub.pull
+  #   sub.delay 120, received_messages
+  #
+  # == Listening for Messages
+  #
+  # Long running workers are easy to create with +listen+, which runs an
+  # infinitely blocking loop to process messages as they are received. (See
+  # Subscription#listen)
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   pubsub = gcloud.pubsub
+  #
+  #   sub = pubsub.subscription "my-topic-sub"
+  #   sub.listen do |msg|
+  #     # process msg
+  #   end
+  #
+  # Messages are retrieved in batches for efficiency. The number of messages
+  # pulled per batch can be limited with the +max+ option:
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   pubsub = gcloud.pubsub
+  #
+  #   sub = pubsub.subscription "my-topic-sub"
+  #   sub.listen max: 20 do |msg|
+  #     # process msg
+  #   end
+  #
+  # When processing time and the acknowledgement deadline are a concern,
+  # messages can be automatically acknowledged as they are pulled with the
+  # +autoack+ option:
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   pubsub = gcloud.pubsub
+  #
+  #   sub = pubsub.subscription "my-topic-sub"
+  #   sub.listen autoack: true do |msg|
+  #     # process msg
+  #   end
+  #
+  module Pubsub
+  end
+end