uc3-dmp-api-core 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7033c9283948ba0b3b9a2cea45d17ba843f42b2d78f8a32f003d88cce9532c9e
+  data.tar.gz: 7fbfe97abe42ee3005c37b246eac7eece4358cceb42a9c7d8fe4e1ae13f5c8ac
+SHA512:
+  metadata.gz: d253494718f77f3cbf5e72d65f331eebe00a5fc327551c6478c1c144c29028b6bbab79395a76a15883049ff89482011015bb8387116407cb1d27edc64c8e24ae
+  data.tar.gz: fc0776170a8a1237f4b66564b83b12ff991548d6f98f4e8f43cce35414c3ba6a70e5e86f62155f710d09d230626510c46dcd64ad144d740dd7f5814e73abcf2b

data/README.md

@@ -0,0 +1,8 @@
+# Uc3DmpApiCore
+
+Basic helper classes used by the DMPTool Lambda functions.
+
+- Logger: Helper for logging messages and errors to CloudWatch
+- Notifier: Helper for sending emails via SNS and sending events to EventBridge
+- Responder: Helper that formats API responses in a standardized way
+- SsmReader: Helper that fetches values from the SSM parameter store

data/lib/uc3-dmp-api-core/logger.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative './notifier'
+
+module Uc3DmpApiCore
+  # Standardized ways for logging messages and errors to CloudWatch
+  #
+  # Methods expect the following inputs:
+  #   - source:       the name of the Lambda function or Layer file
+  #   - message:      the error message as a String or Array of Strings
+  #   - details:      any additional context as a Hash
+  #   - event:        the Lambda event if available
+  #
+  # --------------------------------------------------------------------------------
+  class Logger
+    class << self
+      # rubocop:disable Metrics/AbcSize
+      def log_error(source:, message:, details: {}, event: {})
+        return false if source.nil? || message.nil?
+
+        message = message.join(', ') if message.is_a?(Array)
+        # Is there a better way here than just 'print'? This ends up in the CloudWatch logs
+        puts "ERROR: #{source} - #{message}"
+        puts " - DETAILS: #{details.to_json}" if details.is_a?(Hash) && details.keys.any?
+        puts " - EVENT: #{event.to_json}" if event.is_a?(Hash) && event.keys.any?
+
+        Notifier.notify_administrator(source: source, details: details, event: event)
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      def log_message(source:, message:, details: {}, event: {})
+        return false if source.nil? || message.nil?
+
+        message = message.join(', ') if message.is_a?(Array)
+
+        # Is there a better way here than just 'print'? This ends up in the CloudWatch logs
+        puts "INFO: #{source} - #{message}"
+        puts " - DETAILS: #{details.to_json}" if details.is_a?(Hash) && details.keys.any?
+        true
+      end
+    end
+  end
+end

data/lib/uc3-dmp-api-core/notifier.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'aws-sdk-sns'
+
+module Uc3DmpApiCore
+  # Helper functions to send emails via SNS or publish events to EventBridge
+  class Notifier
+    class << self
+      # Sends the Administrator an email notification
+      # --------------------------------------------------------------------------------
+      # rubocop:disable Metrics/AbcSize
+      def notify_administrator(source:, details:, event: {})
+        Aws::SNS::Client.new.publish(
+          topic_arn: ENV.fetch('SNS_FATAL_ERROR_TOPIC', nil),
+          subject: "DMPTool - fatal error in - #{source}",
+          message: _build_admin_message(source: source, details: details, event: event)
+        )
+        true
+      rescue Aws::Errors::ServiceError => e
+        puts "Uc3DmpCore.Notifier - Unable to notify administrator via SNS! - #{e.message} - on #{source}"
+        puts " - EVENT: #{event.to_json}" if event.is_a?(Hash) && event.keys.any?
+        puts " - DETAILS: #{details.to_json}" if details.is_a?(Hash) && details.keys.any?
+        false
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      private
+
+      # Format the Admin email message
+      def _build_admin_message(source:, details:, event: {})
+        payload = "DMPTool #{ENV.fetch('LAMBDA_ENV', 'dev')} has encountered a fatal error within a Lambda function.\n\n /
+          SOURCE: #{source}\n /
+          TIME STAMP: #{Time.now.strftime('%Y-%m-%dT%H:%M:%S%L%Z')}\n /
+          NOTES: Check the CloudWatch logs for additional details.\n\n"
+        payload += "CALLER RECEIVED: #{event.to_json}\n\n" if event.is_a?(Hash) && event.keys.any?
+        payload += "DETAILS: #{details.to_json}\n\n" if details.is_a?(Hash) && details.keys.any?
+        payload += "This is an automated email generated by the Uc3DmpCore.Notifier gem.\n /
+                    Please do not reply to this message."
+      end
+    end
+  end
+end

data/lib/uc3-dmp-api-core/paginator.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Uc3DmpApiCore
+  # Use Rails' ActiveResource to communicate with the DMPHub REST API
+  class Paginator
+    DEFAULT_PAGE = 1
+    DEFAULT_PER_PAGE = 25
+    MAXIMUM_PER_PAGE = 250
+
+    class << self
+      def paginate(params: {}, results:)
+        return results unless results.is_a?(Array) && results.any? && params.is_a?(Hash)
+
+        current = _current_page(item_count: item_count, params: params)
+        # Just return as is if there is only one page
+        return results if current[:total_pages] == 1 || current[:per_page] >= results.length
+
+        # Calculate the offset and extract those results
+        offset = current[:page] == 1 ? 0 : (current[:page] - 1) * current[:per_page]
+        results[offset,(current[:per_page] - 1)]
+      end
+
+      # Construct the pagination meta information that will be included in the response
+      def pagination_meta(url:, item_count: 0, params: {})
+        current = _current_page(item_count: item_count, params: params)
+        {
+          page: current[:page],
+          per_page: current[:per_page],
+          total_items: item_count,
+          first: _pagination_link(url: url, target_page: 1, per_page: per_page),
+          prev: _pagination_link(url: url, target_page: page - 1, per_page: per_page),
+          next: _pagination_link(url: url, target_page: page + 1, per_page: per_page),
+          last: _pagination_link(url: url, target_page: total_pages, per_page: per_page)
+        }.compact
+      end
+
+      private
+
+      # Fetch the current :page and :per_page from the params or use the defaults
+      def _current_page(item_count: 0, params: {})
+        page = params.fetch('page', DEFAULT_PAGE)
+        page = DEFAULT_PAGE if page <= 1
+        per_page = params.fetch('per_page', DEFAULT_PER_PAGE)
+        per_page = DEFAULT_PER_PAGE if per_page >= MAXIMUM_PER_PAGE || per_page <= 1
+
+        total_pages = _page_count(total: item_count, per_page: per_page)
+        page = total_pages if page > total_pages
+
+        { page: page.to_i, per_page: per_page.to_i, total_pages: total_pages.to_i }
+      end
+
+      # Generate a pagination link
+      # --------------------------------------------------------------------------------
+      def _pagination_link(url:, target_page:, per_page: DEFAULT_PER_PAGE)
+        return nil if url.nil? || target_page.nil?
+
+        link = _url_without_pagination(url: url)
+        return nil if link.nil?
+
+        link += '?' unless link.include?('?')
+        link += '&' unless link.end_with?('&') || link.end_with?('?')
+        "#{link}page=#{target_page}&per_page=#{per_page}"
+      end
+
+      # Determine the total number of pages
+      # --------------------------------------------------------------------------------
+      def _page_count(total:, per_page: DEFAULT_PER_PAGE)
+        return 1 if total.nil? || per_page.nil? || !total.positive? || !per_page.positive?
+
+        (total.to_f / per_page).ceil
+      end
+
+      # Remove the pagination query parameters from the URL
+      # --------------------------------------------------------------------------------
+      def _url_without_pagination(url:)
+        return nil if url.nil? || !url.is_a?(String)
+
+        parts = url.split('?')
+        out = parts.first
+        query_args = parts.length <= 1 ? [] : parts.last.split('&')
+        query_args = query_args.reject { |arg| arg.start_with?('page=') || arg.start_with?('per_page=') }
+        return out unless query_args.any?
+
+        "#{out}?#{query_args.join('&')}"
+      end
+    end
+  end
+end

data/lib/uc3-dmp-api-core/responder.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Uc3DmpApiCore
+  # Use Rails' ActiveResource to communicate with the DMPHub REST API
+  class Responder
+    DEFAULT_PAGE = 1
+    DEFAULT_PER_PAGE = 25
+    MAXIMUM_PER_PAGE = 250
+
+    DEFAULT_STATUS_CODE = 500
+
+    TIMESTAMP_FORMAT = '%Y-%m-%dT%H:%M:%S%L%Z'
+
+    MSG_INVALID_ARGS = 'Invalid arguments'
+
+    class << self
+      # Standardized Lambda response
+      #
+      # Expects the following inputs:
+      #   - status:       an HTTP status code (defaults to DEFAULT_STATUS_CODE)
+      #   - items:        an array of Hashes
+      #   - errors:       and array of Strings
+      #   - args:         currently only allows for the Lambda :event
+      #
+      # Returns a hash that is a valid Lambda API response
+      # --------------------------------------------------------------------------------
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      def respond(status: DEFAULT_STATUS_CODE, items: [], errors: [], **args)
+        url = _url_from_event(event: args[:event]) || SsmReader.get_ssm_value(key: 'api_base_url')
+        return { statusCode: DEFAULT_STATUS_CODE, body: { errors: ["#{MSG_INVALID_ARGS} - resp"] } } if url.nil?
+
+        errors = [errors] unless errors.nil? || errors.is_a?(Array)
+        item_count = items.is_a?(Array) ? items.length : 0
+        page = args[:page] || DEFAULT_PAGE
+        per_page = args[:per_page] || DEFAULT_PER_PAGE
+
+        unless ENV['CORS_ORIGIN'].nil?
+          cors_headers = {
+            'Access-Control-Allow-Headers': ENV['CORS_HEADERS'],
+            'Access-Control-Allow-Origin': ENV['CORS_ORIGIN'],
+            'Access-Control-Allow-Methods': ENV['CORS_METHODS']
+          }
+        end
+
+        body = {
+          status: status.to_i,
+          requested: url,
+          requested_at: Time.now.strftime(TIMESTAMP_FORMAT),
+          total_items: item_count,
+          items: items.is_a?(Array) ? items.compact : []
+        }
+
+        body[:errors] = errors if errors.is_a?(Array) && errors.any?
+        body = _paginate(url: url, item_count: item_count, body: body, page: page, per_page: per_page)
+
+        # If this is a server error, then notify the administrator!
+        log_error(source: url, message: errors, details: body, event: args[:event]) if status == 500
+
+        { statusCode: status.to_i, body: body.to_json, headers: cors_headers.nil? ? {} : cors_headers }
+      rescue StandardError => e
+        puts "LambdaLayer: Responder.respond - #{e.message}"
+        puts " - STACK: #{e.backtrace}"
+        { statusCode: DEFAULT_STATUS_CODE, body: { errors: ["#{MSG_INVALID_ARGS} - resp err"] } }
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+      private
+
+      # Figure out the requested URL from the Lambda event hash
+      # --------------------------------------------------------------------------------
+      def _url_from_event(event:)
+        return '' unless event.is_a?(Hash)
+
+        url = event.fetch('path', '/')
+        return url if event['queryStringParameters'].nil?
+
+        "#{url}?#{event['queryStringParameters'].map { |k, v| "#{k}=#{v}" }.join('&')}"
+      end
+    end
+  end
+end

data/lib/uc3-dmp-api-core/ssm_reader.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'aws-sdk-ssm'
+
+module Uc3DmpApiCore
+  # ----------------------------------------------------
+  # SSM Parameter Store Helper
+  #
+  # Shared helper methods for accessing SSM parameters
+  # ----------------------------------------------------
+  class SsmReader
+    SOURCE = 'SsmReader gem'
+
+    class << self
+      # Return all of the available keys
+      def available_keys
+        _ssm_keys.keys
+      end
+
+      # Fetch the value for the specified :key
+      # ----------------------------------------------------
+      # rubocop:disable Metrics/AbcSize
+      def get_ssm_value(key:, provenance_name: nil)
+        full_key = _ssm_keys[:"#{key.downcase.to_s}"] unless key.nil?
+        return nil if full_key.nil?
+
+
+        key_vals = { env: ENV.fetch('LAMBDA_ENV', 'dev').to_s.downcase }
+        # Swap in the provenance name if applicable
+        key_vals[:provenance] = provenance_name unless provenance_name.nil? ||
+                                                       !full_key.include?('%{provenance}')
+        fetch_value(key: format(full_key, key_vals))
+      rescue Aws::Errors::ServiceError => e
+        Logger.log_error(
+          source: "#{SOURCE} - looking for #{key}", message: e.message, details: e.backtrace
+        )
+        nil
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      # Call SSM to get the value for the specified key
+      def fetch_value(key:)
+        resp = Aws::SSM::Client.new.get_parameter(name: key, with_decryption: true)
+        resp.nil? || resp.parameter.nil? ? nil : resp.parameter.value
+      end
+
+      # Checks to see if debug mode has been enabled in SSM
+      # ----------------------------------------------------
+      def debug_mode?
+        get_ssm_value(key: _ssm_keys[:debug_mode])&.downcase&.strip == 'true'
+      end
+
+      private
+
+      # DMPTool/DMPHub SSM keys. See the installation guide for information about how these values are used
+      #    https://github.com/CDLUC3/dmp-hub-cfn/wiki/installation-and-setup#required-ssm-parameters
+      def _ssm_keys
+        {
+          administrator_email: '/uc3/dmp/hub/%{env}/AdminEmail',
+          api_base_url: '/uc3/dmp/hub/%{env}/ApiBaseUrl',
+          base_url: '/uc3/dmp/hub/%{env}/BaseUrl',
+          debug_mode: '/uc3/dmp/hub/%{env}/Debug',
+
+          dmp_id_api_url: '/uc3/dmp/hub/%{env}/EzidApiUrl',
+          dmp_id_base_url: '/uc3/dmp/hub/%{env}/EzidBaseUrl',
+          dmp_id_client_id: '/uc3/dmp/hub/%{env}/EzidUsername',
+          dmp_id_client_name: '/uc3/dmp/hub/%{env}/EzidHostingInstitution',
+          dmp_id_client_secret: '/uc3/dmp/hub/%{env}/EzidPassword',
+          dmp_id_debug_mode: '/uc3/dmp/hub/%{env}/EzidDebugMode',
+          dmp_id_paused: '/uc3/dmp/hub/%{env}/EzidPaused',
+          dmp_id_shoulder: '/uc3/dmp/hub/%{env}/EzidShoulder',
+
+          provenance_api_client_id: '/uc3/dmp/hub/%{env}/%{provenance}/client_id',
+          provenance_api_client_secret: '/uc3/dmp/hub/%{env}/%{provenance}/client_secret',
+
+          s3_bucket_url: '/uc3/dmp/hub/%{env}/S3CloudFrontBucketUrl',
+          s3_access_point: '/uc3/dmp/hub/%{env}/S3CloudFrontBucketAccessPoint',
+
+          rds_username: '/uc3/dmp/tool/%{env}/RdsUsername',
+          rds_pasword: '/uc3/dmp/tool/%{env}/RdsPassword',
+
+          dynamo_table_name: '/uc3/dmp/hub/%{env}/DynamoTableName'
+        }
+      end
+    end
+  end
+end

data/lib/uc3-dmp-api-core/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Uc3DmpApiCore
+  VERSION = '0.0.1'
+end

data/lib/uc3-dmp-api-core.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'aws-sdk-sns'
+require 'aws-sdk-ssm'
+
+require 'uc3-dmp-api-core/notifier'
+require 'uc3-dmp-api-core/paginator'
+require 'uc3-dmp-api-core/responder'
+require 'uc3-dmp-api-core/ssm_reader'
+
+module Uc3DmpApiCore
+  # General HTTP Response Messages
+  # ----------------------------------------
+  MSG_SUCCESS = 'Success'
+  MSG_INVALID_ARGS = 'Invalid arguments.' # For HTTP 400 (Bad request)
+  MSG_SERVER_ERROR = 'Unable to process your request at this time.' # For HTTP 500 (Server error)
+end

metadata

@@ -0,0 +1,149 @@
+--- !ruby/object:Gem::Specification
+name: uc3-dmp-api-core
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Brian Riley
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2023-04-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-sns
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-ssm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.150'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.150'
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 11.1.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 11.1.3
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.9.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.9.0
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.88.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.88.0
+description: Helpers for SSM, EventBridge, standardizing responses/errors
+email:
+- brian.riley@ucop.edu
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/uc3-dmp-api-core.rb
+- lib/uc3-dmp-api-core/logger.rb
+- lib/uc3-dmp-api-core/notifier.rb
+- lib/uc3-dmp-api-core/paginator.rb
+- lib/uc3-dmp-api-core/responder.rb
+- lib/uc3-dmp-api-core/ssm_reader.rb
+- lib/uc3-dmp-api-core/version.rb
+homepage: https://github.com/CDLUC3/dmp-hub-cfn/blob/main/src/sam/gems/uc3-dmp-api-core
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key: 
+specification_version: 4
+summary: DMPTool gem that provides general support for Lambda functions
+test_files: []