alpha-one/src/http.coffee

ideas about recurring tasks in Web- and Backend-Application building

############################################################################################################
TRM                       = require 'coffeenode-trm'
rpr                       = TRM.rpr.bind TRM
badge                     = 'α1/HTTP'
log                       = TRM.get_logger 'plain',     badge
info                      = TRM.get_logger 'info',      badge
whisper                   = TRM.get_logger 'whisper',   badge
alert                     = TRM.get_logger 'alert',     badge
debug                     = TRM.get_logger 'debug',     badge
warn                      = TRM.get_logger 'warn',      badge
help                      = TRM.get_logger 'help',      badge
echo                      = TRM.echo.bind TRM


#===========================================================================================================
# HTTP STUFF
#-----------------------------------------------------------------------------------------------------------
@_add_options = ( request, response ) ->
  request[ 'A1' ][ 'HTTP' ] =
    'status':           200
    'headers':          {}
  return null

#-----------------------------------------------------------------------------------------------------------
@_get_http_options = ( request ) ->
  R = request[ 'A1' ]?[ 'HTTP' ]
  throw new Error "unable to write headers with no `add_request_options` middleware in stack" unless R?
  return R

#-----------------------------------------------------------------------------------------------------------
@write_header = ( request, response ) ->
  HTTP                        = @_get_http_options request
  status                      = HTTP[ 'status'  ] ? 200
  headers                     = HTTP[ 'headers' ]?= {}
  headers[ 'Content-Type' ]  ?= 'text/html'
  # headers[ 'Connection'   ]  ?= 'keep-alive'
  # log TRM.lime '©89', request[ 'A1' ]
  #.........................................................................................................
  return response.writeHeader status, headers

#-----------------------------------------------------------------------------------------------------------
@set_status = ( request, response, status, location ) ->
  HTTP                    = @_get_http_options request
  headers                 = HTTP[ 'headers' ]?= {}
  HTTP[     'status'    ] = status
  headers[  'location'  ] = location if location?
  # debug '©4r', HTTP
  return null

#-----------------------------------------------------------------------------------------------------------
@redirect = ( request, response, location ) ->
  log TRM.blue 'redirect'
  return @set_status request, response, 302, location

#-----------------------------------------------------------------------------------------------------------
@bounce = ( request, response, location ) ->
  ### Issue an HTTP 302 response redirecting the client to the given location. A (plain-text) cookie by
  the name of `comes-from` will be set that contains the route of the request that caused this redirect;
  this may later be used by `HTTP.back_to` to steer the client back to their original location, and is
  useful for login / signup and logout / signout scenarios, where the user may hit upon a restricted
  address, gets redirected to a login page, and then back to the first location. ###
  log TRM.blue 'bounce'
  # request.flash 'info', "you have been redirected: #{request[ 'url' ]} -> #{location}"
  response.cookie 'comes-from', request[ 'url' ], path: '/'
  #.........................................................................................................
  return @redirect request, response, location

#-----------------------------------------------------------------------------------------------------------
@back_to = ( request, response, location ) ->
  ### Like `bounce`, but reads a `comes-from` cookie to find the redirect location. If no
  cookie `comes-from` is found, the `location` argument is used instead; if no `location` argument was
  given, `/` is used. ###
  log TRM.blue 'back_to'
  location = ( request[ 'cookies' ]?[ 'comes-from' ] ? location ) ? '/'
  #.........................................................................................................
  return @redirect request, response, location

#-----------------------------------------------------------------------------------------------------------
@ok = ( request, response ) ->
  return @set_status request, response, 200

#-----------------------------------------------------------------------------------------------------------
@server_error = ( request, response ) ->
  return @set_status request, response, 500

#-----------------------------------------------------------------------------------------------------------
@not_found = ( request, response ) ->
  return @set_status request, response, 404