Class Hoodoo::Services::Middleware < Object

# File lib/hoodoo/services/middleware/middleware.rb, line 290
def self.clear_memcached_configuration_cache!
  @@memcached_host = nil
end

# File lib/hoodoo/services/middleware/middleware.rb, line 371
def self.clear_queue_configuration_cache!
  @@amq_uri = nil
end

# File lib/hoodoo/services/middleware/middleware.rb, line 352
def self.clear_session_store_configuration_cache!
  @@session_store_engine = nil
  @@session_store_uri    = nil
end

# File lib/hoodoo/services/middleware/middleware.rb, line 398
def self.de_facto_path_for( resource, version )
  "/#{ version }/#{ resource }"
end

# File lib/hoodoo/services/middleware/middleware.rb, line 244
def self.environment
  @@environment ||= Hoodoo::StringInquirer.new( ENV[ 'RACK_ENV' ] || 'development' )
end

# File lib/hoodoo/services/middleware/middleware.rb, line 548
def self.flush_services_for_test
  @@services     = []
  @@service_name = nil

  ObjectSpace.each_object( self ) do | middleware_instance |
    discoverer = middleware_instance.instance_variable_get( '@discoverer' )
    discoverer.flush_services_for_test() if discoverer.respond_to?( :flush_services_for_test )
  end
end

# File lib/hoodoo/services/middleware/middleware.rb, line 255
def self.has_memcached?
  $stderr.puts( 'Hoodoo::Services::Middleware::Middleware#has_memcached? is deprecated - use #has_session_store?' )

  m = self.memcached_host()
  m.nil? == false && m.empty? == false
end

# File lib/hoodoo/services/middleware/middleware.rb, line 265
def self.has_session_store?
  config = self.session_store_uri()
  config.nil? == false && config.empty? == false
end

# File lib/hoodoo/services/middleware/middleware.rb, line 438
def self.logger
  @@logger # See self.set_up_basic_logging and self.set_logger
end

# File lib/hoodoo/services/middleware/middleware.rb, line 279
def self.memcached_host

  # See also ::clear_memcached_configuration_cache!.
  #
  @@memcached_host ||= ENV[ 'MEMCACHED_HOST' ] || ENV[ 'MEMCACHE_URL' ]

end

# File lib/hoodoo/services/middleware/middleware.rb, line 562
def initialize( app )

  service_container = app

  if defined?( NewRelic ) &&
     defined?( NewRelic::Agent ) &&
     defined?( NewRelic::Agent::Instrumentation ) &&
     defined?( NewRelic::Agent::Instrumentation::MiddlewareProxy ) &&
     service_container.is_a?( NewRelic::Agent::Instrumentation::MiddlewareProxy )

    if service_container.respond_to?( :target )
      service_container = service_container.target()
    else
      raise "Hoodoo::Services::Middleware instance created with NewRelic-wrapped Service entity, but NewRelic API is not as expected by Hoodoo; incompatible NewRelic version."
    end
  end

  unless service_container.is_a?( Hoodoo::Services::Service )
    raise "Hoodoo::Services::Middleware instance created with non-Service entity of class '#{ service_container.class }' - is this the last middleware in the chain via 'use()' and is Rack 'run()'-ing the correct thing?"
  end

  # Collect together the implementation instances and the matching regexps
  # for endpoints. An array of hashes.
  #
  # Key              Value
  # =======================================================================
  # regexp           Regexp for +String#match+ on the URI path component
  # interface        Hoodoo::Services::Interface subclass associated with
  #                  the endpoint regular expression in +regexp+
  # actions          Set of symbols naming allowed actions
  # implementation   Hoodoo::Services::Implementation subclass *instance* to
  #                  use on match
  #
  @@services = service_container.component_interfaces.map do | interface |

    if interface.nil? || interface.endpoint.nil? || interface.implementation.nil?
      raise "Hoodoo::Services::Middleware encountered invalid interface class #{ interface } via service class #{ service_container.class }"
    end

    # If anything uses a public interface, we need to tell ourselves that
    # the early exit session check can't be done.
    #
    interfaces_have_public_methods() unless interface.public_actions.empty?

    # There are two routes to an implementation - one via the custom path
    # given through its 'endpoint' declaration, the other a de facto path
    # determined from the unmodified version and resource name. Both lead
    # to the same implementation instance.
    #
    implementation_instance = interface.implementation.new

    # Regexp explanation:
    #
    # Match "/", the version text, "/", the endpoint text, then either
    # another "/", a "." or the end of the string, followed by capturing
    # everything else. Match data index 1 will be whatever character (if
    # any) followed after the endpoint ("/" or ".") while index 2 contains
    # everything else.
    #
    custom_path   = "/v#{ interface.version }/#{ interface.endpoint }"
    custom_regexp = /^\/v#{ interface.version }\/#{ interface.endpoint }(\.|\/|$)(.*)/

    # Same as above, but for the de facto routing.
    #
    de_facto_path   = self.class.de_facto_path_for( interface.resource, interface.version )
    de_facto_regexp = /^\/#{ interface.version }\/#{ interface.resource }(\.|\/|$)(.*)/

    Hoodoo::Services::Discovery::ForLocal.new(
      :resource                => interface.resource,
      :version                 => interface.version,
      :base_path               => custom_path,
      :routing_regexp          => custom_regexp,
      :de_facto_base_path      => de_facto_path,
      :de_facto_routing_regexp => de_facto_regexp,
      :interface_class         => interface,
      :implementation_instance => implementation_instance
    )

  end

  # Determine the service name from the resources above then announce
  # the whole collection to any interested discovery engines.

  sorted_resources = @@services.map() { | service | service.resource }.sort()
  @@service_name   = "service.#{ sorted_resources.join( '_' ) }"

  announce_presence_of( @@services )
end

# File lib/hoodoo/services/middleware/middleware.rb, line 359
def self.on_queue?

  # See also ::clear_queue_configuration_cache!.
  #
  @@amq_uri ||= ENV[ 'AMQ_URI' ]
  @@amq_uri.nil? == false && @@amq_uri.empty? == false

end

# File lib/hoodoo/services/middleware/middleware.rb, line 537
def self.record_host_and_port( options = {} )
  @@recorded_host = options[ :Host ]
  @@recorded_port = options[ :Port ]
end

# File lib/hoodoo/services/middleware/middleware.rb, line 386
def self.service_name
  @@service_name
end

# File lib/hoodoo/services/middleware/middleware.rb, line 329
def self.session_store_engine
  if (
    ! defined?( @@session_store_engine ) ||
    @@session_store_engine.nil?          ||
    @@session_store_engine.empty?
  )
    default = self.has_memcached? ? 'memcached' : ''
    engine = ( ENV[ 'SESSION_STORE_ENGINE' ] || default ).to_sym()

    if Hoodoo::TransientStore::supported_storage_engines.include?( engine )
      @@session_store_engine = engine
    else
      @@session_store_engine = nil
    end
  end

  @@session_store_engine
end

# File lib/hoodoo/services/middleware/middleware.rb, line 303
def self.session_store_uri

  # See also ::clear_session_store_configuration_cache!
  #
  @@session_store_uri ||= ( ENV[ 'SESSION_STORE_URI' ] || self.memcached_host() )

end

# File lib/hoodoo/services/middleware/middleware.rb, line 478
def self.set_log_folder( base_path )
  self.send( :add_file_logging, base_path )
end

# File lib/hoodoo/services/middleware/middleware.rb, line 455
def self.set_logger( logger )
  unless logger.is_a?( Hoodoo::Logger )
    raise "Hoodoo::Communicators::set_logger must be called with an instance of Hoodoo::Logger only"
  end

  @@external_logger = true
  @@logger          = logger
end

# File lib/hoodoo/services/middleware/middleware.rb, line 524
def self.set_test_session( session )
  @@test_session = session
end

# File lib/hoodoo/services/middleware/middleware.rb, line 494
def self.set_verbose_logging( verbose )
  @@verbose_logging = verbose
end

# File lib/hoodoo/services/middleware/middleware.rb, line 513
def self.test_session
  @@test_session
end

# File lib/hoodoo/services/middleware/middleware.rb, line 501
def self.verbose_logging?
  defined?( @@verbose_logging ) ? @@verbose_logging : false
end

# File lib/hoodoo/services/middleware/middleware.rb, line 656
def call( env )

  # Global exception handler - catch problems in service implementations
  # and send back a 500 response as per API documentation (if possible).
  #
  begin

    enable_alchemy_logging_from( env )

    interaction = Hoodoo::Services::Middleware::Interaction.new( env, self )
    debug_log( interaction )

    early_response = preprocess( interaction )
    return early_response unless early_response.nil?

    response = interaction.context.response

    process( interaction )     unless response.halt_processing?
    postprocess( interaction ) unless response.halt_processing?

    return respond_for( interaction )

  rescue => exception
    begin
      if interaction && interaction.context
        ExceptionReporting.contextual_report( exception, interaction.context )
      else
        ExceptionReporting.report( exception, env )
      end

      record_exception( interaction, exception )

      return respond_for( interaction )

    rescue => inner_exception
      begin
        backtrace       = ''
        inner_backtrace = ''

        if self.class.environment.test? || self.class.environment.development?
          backtrace       = exception.backtrace
          inner_backtrace = inner_exception.backtrace
        else
          ''
        end

        @@logger.error(
          'Hoodoo::Services::Middleware#call',
          'Middleware exception in exception handler',
          inner_exception.to_s,
          inner_backtrace.to_s,
          '...while handling...',
          exception.to_s,
          backtrace.to_s
        )
      rescue
        # Ignore logger exceptions. Can't do anything about them. Just
        # try and get the response back to the client now.
      end

      # An exception in the exception handler! Oh dear.
      #
      rack_response = Rack::Response.new
      rack_response.status = 500
      rack_response.write( 'Middleware exception in exception handler' )
      return rack_response.finish

    end
  end
end

# File lib/hoodoo/services/middleware/middleware.rb, line 741
def inter_resource_endpoint_for( resource, version, interaction )
  resource = resource.to_sym
  version  = version.to_i

  # Build a Hash of any options which should be transferred from one
  # endpoint to another for inter-resource calls, along with other
  # options common to local and remote endpoints.

  endpoint_options = {
    :interaction => interaction,
    :locale      => interaction.context.request.locale,
  }

  Hoodoo::Client::Headers::HEADER_TO_PROPERTY.each do | rack_header, description |
    property = description[ :property ]

    if description[ :auto_transfer ] == true
      endpoint_options[ property ] = interaction.context.request.send( property )
    end
  end

  if @discoverer.is_local?( resource, version )

    # For local inter-resource calls, return the middleware's endpoint
    # for that. In turn, if used this calls into #inter_resource_local.

    discovery_result = @@services.find do | entry |
      interface = entry.interface_class
      interface.resource == resource && interface.version == version
    end

    if discovery_result.nil?
      raise "Hoodoo::Services::Middleware\#inter_resource_endpoint_for: Internal error - version #{ version } of resource #{ resource } endpoint is local according to the discovery engine, but no local service discovery record can be found"
    end

    endpoint_options[ :discovery_result ] = discovery_result

    return Hoodoo::Services::Middleware::InterResourceLocal.new(
      resource,
      version,
      endpoint_options
    )

  else

    # For remote inter-resource calls, use Hoodoo::Client's endpoint
    # factory to get a (say) HTTP or AMQP contact endpoint, but then
    # wrap it with the middleware's remote call endpoint, since the
    # request requires extra processing before it goes to the Client
    # (e.g. session permission augmentation) and the result needs
    # extra processing before it is returned to the caller (e.g.
    # delete an augmented session, annotate any errors from call).

    endpoint_options[ :discoverer ] = @discoverer
    endpoint_options[ :session    ] = interaction.context.session

    wrapped_endpoint = Hoodoo::Client::Endpoint.endpoint_for(
      resource,
      version,
      endpoint_options
    )

    if wrapped_endpoint.is_a?( Hoodoo::Client::Endpoint::AMQP ) && defined?( @@alchemy )
      wrapped_endpoint.alchemy = @@alchemy
    end

    # Using "ForRemote" here is redundant - we could just as well
    # pass wrapped_endpoint directly to an option in the
    # InterResourceRemote class - but keeping "with the pattern"
    # just sort of 'seems right' and might be useful in future.

    discovery_result = Hoodoo::Services::Discovery::ForRemote.new(
      :resource         => resource,
      :version          => version,
      :wrapped_endpoint => wrapped_endpoint
    )

    return Hoodoo::Services::Middleware::InterResourceRemote.new(
      resource,
      version,
      {
        :interaction      => interaction,
        :discovery_result => discovery_result
      }
    )
  end
end

# File lib/hoodoo/services/middleware/middleware.rb, line 870
def inter_resource_local( source_interaction:,
                          discovery_result:,
                          endpoint:,
                          action:,
                          ident:      nil,
                          body_hash:  nil,
                          query_hash: nil )

  # We must construct a call context for the local service. This means
  # a local request object which we fill in with data just as if we'd
  # parsed an inbound HTTP request and a response object that contains
  # the usual default data.

  interface      = discovery_result.interface_class
  implementation = discovery_result.implementation_instance

  # Need to possibly augment the caller's session - same rationale
  # as #local_service_remote, so see that for details.

  session = source_interaction.context.session

  unless session.nil? || source_interaction.using_test_session?
    session = session.augment_with_permissions_for( source_interaction )
  end

  if session == false
    hash = Hoodoo::Client::AugmentedHash.new
    hash.platform_errors.add_error( 'platform.invalid_session' )
    return hash
  end

  mock_rack_env = {
    'HTTP_X_INTERACTION_ID' => source_interaction.interaction_id
  }

  local_interaction = Hoodoo::Services::Middleware::Interaction.new(
    mock_rack_env,
    self,
    session
  )

  local_interaction.target_interface           = interface
  local_interaction.target_implementation      = implementation
  local_interaction.requested_content_type     = source_interaction.requested_content_type
  local_interaction.requested_content_encoding = source_interaction.requested_content_encoding

  # For convenience...

  local_request  = local_interaction.context.request
  local_response = local_interaction.context.response

  # Carry through any endpoint-specified request orientated attributes.

  local_request.locale = endpoint.locale

  Hoodoo::Client::Headers::HEADER_TO_PROPERTY.each do | rack_header, description |
    property        = description[ :property        ]
    property_writer = description[ :property_writer ]

    value = endpoint.send( property )

    local_request.send( property_writer, value ) unless value.nil?
  end

  # Initialise the response data.

  set_common_response_headers( local_interaction )
  update_response_for( local_response, interface )

  # Work out what kind of result the caller is expecting.

  result_class = if action == :list
    Hoodoo::Client::AugmentedArray
  else
    Hoodoo::Client::AugmentedHash
  end

  # Add errors from the local service response into an augmented object
  # for responding early (via a Proc for internal reuse later).

  add_local_errors = Proc.new {
    result                  = result_class.new
    result.response_options = Hoodoo::Client::Headers.x_header_to_options(
      local_response.headers
    )

    result.platform_errors.merge!( local_response.errors )
    result
  }

  # Figure out initial action / authorisation results for this request.
  # We may still have to construct a context and ask the service after.

  upc  = []
  upc << ident unless ident.nil? || ident.empty?

  local_interaction.requested_action = action
  authorisation                      = determine_authorisation( local_interaction )

  # In addition, check security on any would-have-been-a-secured-header
  # property.

  return add_local_errors.call() if local_response.halt_processing?

  Hoodoo::Client::Headers::HEADER_TO_PROPERTY.each do | rack_header, description |

    next if description[ :secured ] != true
    next if endpoint.send( description[ :property ] ).nil?

    real_header = description[ :header ]

    if (
         session.respond_to?( :scoping ) == false ||
         session.scoping.respond_to?( :authorised_http_headers ) == false ||
         session.scoping.authorised_http_headers.respond_to?( :include? ) == false ||
         (
           session.scoping.authorised_http_headers.include?( rack_header ) == false &&
           session.scoping.authorised_http_headers.include?( real_header ) == false
         )
       )

      local_response.errors.add_error( 'platform.forbidden' )
      break
    end
  end

  return add_local_errors.call() if local_response.halt_processing?

  deal_with_x_assume_identity_of( local_interaction )

  return add_local_errors.call() if local_response.halt_processing?

  # Construct the local request details.

  local_request.uri_path_components = upc
  local_request.uri_path_extension  = ''

  unless query_hash.nil?
    query_hash = Hoodoo::Utilities.stringify( query_hash )

    # This is for inter-resource local calls where a service author
    # specifies ":_embed => 'foo'" accidentally, forgetting that it
    # should be a single element array. It's such a common mistake
    # that we tolerate it here. Same for "_reference".

    data = query_hash[ '_embed' ]
    query_hash[ '_embed' ] = [ data ] if data.is_a?( ::String ) || data.is_a?( ::Symbol )

    data = query_hash[ '_reference' ]
    query_hash[ '_reference' ] = [ data ] if data.is_a?( ::String ) || data.is_a?( ::Symbol )

    # Regardless, make sure embed/reference array data contains strings.

    query_hash[ '_embed'     ].map!( &:to_s ) unless query_hash[ '_embed'     ].nil?
    query_hash[ '_reference' ].map!( &:to_s ) unless query_hash[ '_reference' ].nil?

    process_query_hash( local_interaction, query_hash )
  end

  local_request.body = body_hash

  # The inter-resource local backend does not accept or process the
  # equivalent of the X-Resource-UUID "set the ID to <this>" HTTP
  # header, so we do not call "maybe_update_body_data_for()" here;
  # we only need to validate it.
  #
  if ( action == :create || action == :update )
    validate_body_data_for( local_interaction )
  end

  return add_local_errors.call() if local_response.halt_processing?

  # Can now, if necessary, do a final check with the target endpoint
  # for authorisation.

  if authorisation == Hoodoo::Services::Permissions::ASK
    ask_for_authorisation( local_interaction )
    return add_local_errors.call() if local_response.halt_processing?
  end

  # Dispatch the call.

  debug_log( local_interaction, 'Dispatching local inter-resource call', local_request.body )
  dispatch( local_interaction )

  # If we get this far the interim session isn't needed. We might have
  # exited early due to errors above and left this behind, but that's not
  # the end of the world - it'll expire out of the Hoodoo::TransientStore
  # eventually.
  #
  if session &&
     source_interaction.context &&
     source_interaction.context.session &&
     session.session_id != source_interaction.context.session.session_id

    # Ignore errors, there's nothing much we can do about them and in
    # the worst case we just have to wait for this to expire naturally.

    session.delete_from_store()
  end

  # Extract the returned data, handling error conditions.

  if local_response.halt_processing?
    result = result_class.new
    result.set_platform_errors(
      annotate_errors_from_other_resource( local_response.errors )
    )

  else
    body = local_response.body

    if action == :list && body.is_a?( ::Array )
      result                        = Hoodoo::Client::AugmentedArray.new( body )
      result.dataset_size           = local_response.dataset_size
      result.estimated_dataset_size = local_response.estimated_dataset_size

    elsif action != :list && body.is_a?( ::Hash )
      result = Hoodoo::Client::AugmentedHash[ body ]

    elsif local_request.deja_vu && body == ''
      result = result_class.new

    else
      raise "Hoodoo::Services::Middleware: Unexpected response type '#{ body.class.name }' received from a local inter-resource call for action '#{ action }'"

    end

  end

  result.response_options = Hoodoo::Client::Headers.x_header_to_options(
    local_response.headers
  )

  return result
end

# File lib/hoodoo/services/middleware/middleware.rb, line 1117
def monkey_log_inbound_request( interaction )

  data = build_common_log_data_for( interaction )

  # Annoying dance required to extract all HTTP header data from Rack.

  env     = interaction.rack_request.env
  headers = env.select do | key, value |
    key.to_s.match( /^HTTP_/ )
  end

  headers[ 'CONTENT_TYPE'   ] = env[ 'CONTENT_TYPE'   ]
  headers[ 'CONTENT_LENGTH' ] = env[ 'CONTENT_LENGTH' ]

  data[ :payload ] = {
    :method  => env[ 'REQUEST_METHOD', ],
    :scheme  => env[ 'rack.url_scheme' ],
    :host    => env[ 'SERVER_NAME'     ],
    :port    => env[ 'SERVER_PORT'     ],
    :script  => env[ 'SCRIPT_NAME'     ],
    :path    => env[ 'PATH_INFO'       ],
    :query   => env[ 'QUERY_STRING'    ],
    :headers => headers
  }

  # Deal with body data and security issues.

  secure    = true
  interface = interaction.target_interface
  action    = interaction.requested_action

  unless interface.nil? || action.nil?
    secure_log_actions = interface.secure_log_for()
    secure_type        = secure_log_actions[ action ]

    # Allow body logging if there's no security specified for this action
    # or the security is specified for the response only (since we log the
    # request here).
    #
    # This means values of :both or :request will leave "secure" unchanged,
    # as will any other unexpected value that might get specified.

    secure = false if secure_type.nil? || secure_type == :response
  end

  # Compile the remaining log payload and send it.

  unless secure
    body = interaction.rack_request.body.read( MAXIMUM_LOGGED_PAYLOAD_SIZE )
           interaction.rack_request.body.rewind()

    data[ :payload ][ :body ] = body
  end

  @@logger.report(
    :info,
    :Middleware,
    :inbound,
    data
  )

  return nil
end