lambda_wrap 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5f48ab03f6ee01f4084324fd582489720820a060
-  data.tar.gz: f7a1b100285e4fd602f654211dc0ac6a34cf1a8c
+  metadata.gz: 1b0185f2b09d7ebb650e894aaddd7d05b78d2a37
+  data.tar.gz: 96c6d4ccc733e983018f4c957015972be4f9e1dc
 SHA512:
-  metadata.gz: ed51f65ba43fe439c31319287b33e4f04e5f59f1d4385c05408713354e1529a20f1cf99f83ae1bca4ce7866fb9a7cd9af2ed504064b4e51eb29b5ebd7a77dbf8
-  data.tar.gz: 4fece3ef3a2758a300cb838ab295fdabbf502a3576b30fd307e19666b0061594fc3d50438b4becc1942e7057eb414f2b767fbeec96e0c510fe78ce2b1c5bdde0
+  metadata.gz: 0c75377c2eeaf091657c49303165f04e454f3183894d71afe6b427e51c24986f4762fc17d50958ff0bea284e5cd7e565cd53b5e0d70ea79914d311db3aa1c282
+  data.tar.gz: 5681101d09354da961ff4f847c73a42769390a148d25099f3ded29fd7fb74796113a35197615199a287b1213b448ae248a3f278bd4f285d0879eb8c79c1357e5

data/lib/lambda_wrap/api_gateway_manager.rb

@@ -3,8 +3,18 @@ require_relative 'aws_setup'
 
 module LambdaWrap
 	
+	##
+	# The ApiGatewayManager simplifies downloading the aws-apigateway-importer binary,
+	# importing a {swagger configuration}[http://swagger.io], and managing API Gateway stages.
+	#
+	# Note: The concept of an environment of the LambdaWrap gem matches a stage in AWS ApiGateway terms.
 	class ApiGatewayManager
 		
+		##
+		# The constructor does some basic setup
+		# * Validating basic AWS configuration
+		# * Creating the underlying client to interact with the AWS SDK.
+		# * Defining the temporary path of the api-gateway-importer jar file
 		def initialize()
 			AwsSetup.new.validate()
 			# AWS api gateway client
@@ -13,6 +23,15 @@ module LambdaWrap
 			@jarpath = File.join(Dir.tmpdir, 'aws-apigateway-importer-1.0.3-SNAPSHOT-jar-with-dependencies.jar')
 		end
 		
+		##
+		# Downloads the aws-apigateway-importer jar from an S3 bucket.
+		# This is a workaround since aws-apigateway-importer does not provide a binary.
+		# Once a binary is available on the public internet, we'll start using this instead
+		# of requiring users of this gem to upload their custom binary to an S3 bucket. 
+		#
+		# *Arguments*
+		# [s3_bucket]		An S3 bucket from where the aws-apigateway-importer binary can be downloaded.
+		# [s3_key]			The path (key) to the aws-apigateay-importer binary on the s3 bucket.
 		def download_apigateway_importer(s3_bucket, s3_key)	
 			unless File.exist?(@jarpath)
 				puts 'Downloading aws-apigateway-importer jar'
@@ -21,6 +40,14 @@ module LambdaWrap
 			end		
 		end
 		
+		##
+		# Sets up the API gateway by searching whether the API Gateway already exists
+		# and updates it with the latest information from the swagger file.
+		# 
+		# *Arguments*
+		# [api_name]		The name of the API to which the swagger file should be applied to.
+		# [env]				The environment where it should be published (which is matching an API gateway stage)
+		# [swagger_file]	A handle to a swagger file that should be used by aws-apigateway-importer
 		def setup_apigateway(api_name, env, swagger_file)
 			
 			# ensure API is created
@@ -38,6 +65,13 @@ module LambdaWrap
 			
 		end
 		
+		##
+		# Shuts down an environment from the API Gateway. This basically deletes the stage
+		# from the API Gateway, but does not delete the API Gateway itself.
+		#
+		# *Argument*
+		# [api_name]		The name of the API where the environment should be shut down.
+		# [env]				The environment (matching an API Gateway stage) to shutdown.
 		def shutdown_apigateway(api_name, env)
 		
 			api_id = get_existing_rest_api(api_name)
@@ -45,6 +79,11 @@ module LambdaWrap
 			
 		end
 		
+		##
+		# Gets the ID of an existing API Gateway api, or nil if it doesn't exist
+		# 
+		# *Arguments*
+		# [api_name]		The name of the API to be checked for existance
 		def get_existing_rest_api(api_name)
 			
 			apis = @client.get_rest_apis({limit: 500}).data
@@ -58,6 +97,11 @@ module LambdaWrap
 			
 		end
 		
+		##
+		# Creates the API with a given name and returns the id
+		# 
+		# *Arguments*
+		# [api_name]		The name of the API to be created
 		def setup_apigateway_create_rest_api(api_name)
 			
 			puts 'Creating API with name ' + api_name
@@ -67,6 +111,12 @@ module LambdaWrap
 			
 		end
 		
+		##
+		# Invokes the aws-apigateway-importer jar with the required parameter
+		# 
+		# *Arguments*
+		# [api_id]			The AWS ApiGateway id where the swagger file should be applied to.
+		# [swagger_file]	The handle to a swagger definition file that should be imported into API Gateway
 		def setup_apigateway_create_resources(api_id, swagger_file)
 			
 			raise 'API ID not provided' if !api_id
@@ -76,6 +126,12 @@ module LambdaWrap
 			
 		end
 		
+		##
+		# Creates a stage of the currently set resources
+		# 
+		# *Arguments*
+		# [api_id]			The AWS ApiGateway id where the stage should be created at.
+		# [env]				The environment (which matches the stage in API Gateway) to create.
 		def create_stages(api_id, env)
 		
 			deployment_description = 'Deployment of service to ' + env
@@ -84,6 +140,12 @@ module LambdaWrap
 			
 		end
 		
+		##
+		# Deletes a stage of the API Gateway
+		# 
+		# *Arguments*
+		# [api_id]			The AWS ApiGateway id from which the stage should be deleted from.
+		# [env]				The environment (which matches the stage in API Gateway) to delete.
 		def delete_stage(api_id, env)
 			
 			begin
@@ -95,6 +157,8 @@ module LambdaWrap
 			
 		end
 		
+		private :get_existing_rest_api, :setup_apigateway_create_rest_api, :setup_apigateway_create_resources, :create_stages, :delete_stage
+		
 	end
 	
 end

data/lib/lambda_wrap/aws_setup.rb

@@ -1,9 +1,21 @@
 require 'aws-sdk'
 
+##
+# LambdaWrap is a ruby gem that simplifies deployment of AWS Lambda functions that are invoked through AWS API Gateway and optionally include a DynamoDB backend. 
 module LambdaWrap
 
+    ##
+    # Helper class to ensure valid configuration of AWS.
+    # This class is intended for internal use only, but clients can call it before calling any other functionality to ensure early failure. 
     class AwsSetup
         
+        ##
+        # Validates that the setup is correct and that the bundled AWS certificate is used for subsequent calls to the AWS SDK
+        #
+        # *Required environment variables*
+        # [AWS_ACCESS_KEY_ID]       The AWS access key to be used when calling AWS SDK functions
+        # [AWS_SECRET_ACCESS_KEY]   The AWS secret to be used when calling AWS SDK functions
+        # [AWS_REGION]              A valid AWS region to use during configuration.
         def validate()
             
             # validate settings

data/lib/lambda_wrap/dynamo_db_manager.rb

@@ -3,14 +3,34 @@ require_relative 'aws_setup'
 
 module LambdaWrap
 	
+	##
+	# The DynamoDBManager simplifies setting up and destroying a DynamoDB database.
+	#
+	# Note: In case an environment specific DynamoDB tablename such as +<baseTableName>-production+ should be used, then
+	# it has to be injected directly to the methods since not all environments necessarily need separated databases. 
 	class DynamoDbManager
 
+		##
+		# The constructor does some basic setup
+		# * Validating basic AWS configuration
+		# * Creating the underlying client to interact with the AWS SDK.
 		def initialize()
 			AwsSetup.new.validate()
 			# AWS dynamodb client
 			@client = Aws::DynamoDB::Client.new()
 		end
 		
+		##
+		# Publishes the database and awaits until it is fully available. If the table already exists, it only adjusts the read/write
+		# capacities upwards (it doesn't downgrade them to avoid a production environment being impacted with a default setting of an
+		# automated script).
+		#
+		# *Arguments*
+		# [table_name]				The table name of the dynamoDB to be created.
+		# [attribute_definitions]	The dynamoDB attribute definitions to be used when the table is created. See the AWS documentation for details.
+		# [key_schema]				The dynamoDB key definitions to be used when the table is created. See the AWS documentation for details.
+		# [read_capacity]			The read capacity to configure for the dynamoDB table.
+		# [write_capacity]			The write capacity to configure for the dynamoDB table.
 		def publish_database(table_name, attribute_definitions, key_schema, read_capacity, write_capacity)
 			
 			has_updates = false
@@ -57,6 +77,11 @@ module LambdaWrap
 		
 		end
 		
+		##
+		# Deletes a DynamoDB table. It does not wait until the table has been deleted.
+		#
+		# *Arguments*
+		# [table_name]	The dynamoDB table name to delete.
 		def delete_database(table_name)
 			
 			begin
@@ -69,6 +94,11 @@ module LambdaWrap
 			
 		end
 		
+		##
+		# Awaits a given status of a table.
+		#
+		# *Arguments*
+		# [table_name]	The dynamoDB table name to watch until it reaches an active status.
 		def wait_until_table_available(table_name)
 		
 			max_attempts = 24
@@ -89,6 +119,8 @@ module LambdaWrap
 			end
 		
 		end
+		
+		private :wait_until_table_available
 
 	end
 

data/lib/lambda_wrap/lambda_manager.rb

@@ -3,14 +3,30 @@ require_relative 'aws_setup'
 
 module LambdaWrap
 	
+	##
+	# The LambdaManager simplifies creating a package, publishing it to S3, deploying a new version, and setting permissions.
+	#
+	# Note: The concept of an environment of the LambdaWrap gem matches an alias of AWS Lambda. 
 	class LambdaManager
 		
+		##
+		# The constructor does some basic setup
+		# * Validating basic AWS configuration
+		# * Creating the underlying client to interace with the AWS SDK
 		def initialize()
 			AwsSetup.new.validate()
 			# AWS lambda client
 			@client = Aws::Lambda::Client.new()
 		end
 		
+		##
+		# Packages a set of files and node modules into a deployable package.
+		#
+		# *Arguments*
+		# [directory]		A temporary directory to copy all related files before they are packages into a single zip file.
+		# [zipfile]			A path where the deployable package, a zip file, should be stored.
+		# [input_filenames]	A list of file names that contain the source code.
+		# [node_modules]	A list of node modules that need to be included in the package.
 		def package(directory, zipfile, input_filenames, node_modules)
 			
 			FileUtils::mkdir_p directory
@@ -28,6 +44,13 @@ module LambdaWrap
 			
 		end
 		
+		##
+		# Publishes a package to S3 so it can be deployed as a lambda function.
+		#
+		# *Arguments*
+		# [local_lambda_file]	The location of the package that needs to be deployed.
+		# [bucket]				The s3 bucket where the file needs to be uploaded to.
+		# [key]					The S3 path (key) where the package should be stored.
 		def publish_lambda_to_s3(local_lambda_file, bucket, key)
 			
 			# get s3 object
@@ -46,18 +69,28 @@ module LambdaWrap
 			
 		end
 		
-		def deploy_lambda(version_id, function_name, handler)
+		##
+		# Deploys a package that has been uploaded to S3.
+		#
+		# *Arguments*
+		# [bucket]			The S3 bucket where the package can be retrieved from.
+		# [key]				The S3 path (key) where the package can be retrieved from.
+		# [version_id]		The version of the file on S3 to retrieve.
+		# [function_name]	The name of the lambda function.
+		# [handler]			The handler that should be executed for this lambda function.
+		# [lambda_role]		The arn of the IAM role that should be used when executing the lambda function. 
+		def deploy_lambda(bucket, key, version_id, function_name, handler, lambda_role)
 	
 			# create or update function
 			
 			begin
 				func = @client.get_function({function_name: function_name})
-				func_config = @client.update_function_code({function_name: function_name, s3_bucket: S3_BUCKET, s3_key: S3_KEY, s3_object_version: version_id, publish: true}).data
+				func_config = @client.update_function_code({function_name: function_name, s3_bucket: bucket, s3_key: key, s3_object_version: version_id, publish: true}).data
 				puts func_config
 				func_version = func_config.version
 				raise 'Error while publishing existing lambda function ' + function_name if !func_config.version
 			rescue Aws::Lambda::Errors::ResourceNotFoundException
-				func_config = @client.create_function({function_name: function_name, runtime: 'nodejs', role: LAMBDA_ROLE_ARN, handler: handler, code: { s3_bucket: S3_BUCKET, s3_key: S3_KEY }, timeout: 5, memory_size: 128, publish: true, description: 'created by an automated script'}).data
+				func_config = @client.create_function({function_name: function_name, runtime: 'nodejs', role: lambda_role, handler: handler, code: { s3_bucket: bucket, s3_key: key }, timeout: 5, memory_size: 128, publish: true, description: 'created by an automated script'}).data
 				puts func_config
 				func_version = func_config.version
 				raise 'Error while publishing new lambda function ' + function_name if !func_config.version
@@ -69,6 +102,13 @@ module LambdaWrap
 			
 		end
 		
+		##
+		# Creates an alias for a given lambda function version.
+		#
+		# *Arguments*
+		# [function_name]		The lambda function name for which the alias should be created.
+		# [func_version]		The lambda function versino to which the alias should point.
+		# [alias_name]			The name of the alias, matching the LambdaWrap environment concept.
 		def create_alias(function_name, func_version, alias_name)
 			
 			# create or update alias
@@ -85,12 +125,24 @@ module LambdaWrap
 			
 		end
 		
+		##
+		# Removes an alias for a function.
+		#
+		# *Arguments*
+		# [function_name]	The lambda function name for which the alias should be removed.
+		# [alias_name]		The alias to remove.
 		def remove_alias(function_name, alias_name)
 			
 			@client.delete_alias({function_name: function_name, name: alias_name})
 			
 		end
 		
+		##
+		# Adds permissions for API gateway to execute this function.
+		#
+		# *Arguments*
+		# [function_name]		The function name which needs to be executed from API Gateway.
+		# [env]					The environment (matching the function's alias) which needs to be executed from API Gateway. If nil, the permissions are set of the $LATEST version.  
 		def add_api_gateway_permissions(function_name, env)
 			# permissions to execute lambda
 			suffix = (':' + env if env) || '' 
@@ -110,6 +162,8 @@ module LambdaWrap
 			end
 		end
 		
+		private :add_api_gateway_permissions
+		
 	end
 
 end

data/lib/lambda_wrap/zip_file_generator.rb

@@ -1,26 +1,33 @@
 require 'rubygems'
 require 'zip'
-# This is a simple example which uses rubyzip to
-# recursively generate a zip file from the contents of
-# a specified directory. The directory itself is not
-# included in the archive, rather just its contents.
-#
-# Usage:
-# require /path/to/the/ZipFileGenerator/Class
-# directoryToZip = "/tmp/input"
-# outputFile = "/tmp/out.zip"
-# zf = ZipFileGenerator.new(directoryToZip, outputFile)
-# zf.write()
 
 module LambdaWrap
 
+    ##
+    # Allows to easily zip a directory recursively. It's intended for gem internal use only.
+    #
+    # From the original example:
+    # This is a simple example which uses rubyzip to
+    # recursively generate a zip file from the contents of
+    # a specified directory. The directory itself is not
+    # included in the archive, rather just its contents.
+    #
+    # Usage:
+    # require /path/to/the/ZipFileGenerator/Class
+    # directoryToZip = "/tmp/input"
+    # outputFile = "/tmp/out.zip"
+    # zf = ZipFileGenerator.new(directoryToZip, outputFile)
+    # zf.write()
     class ZipFileGenerator
+        
+        ##
         # Initialize with the directory to zip and the location of the output archive.
         def initialize(input_dir, output_file)
             @input_dir = input_dir
             @output_file = output_file
         end
         
+        ##
         # Zip the input directory.
         def write
             entries = Dir.entries(@input_dir) - %w(. ..)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lambda_wrap
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Markus Thurner
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-01-05 00:00:00.000000000 Z
+date: 2016-01-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk