intranet-core 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e210409259e3ae615be11b386d4f59eba6857577
+  data.tar.gz: a971e1e9e6aac78e4ca5fc5503fc47682514a587
+SHA512:
+  metadata.gz: 99566f62fd07cc59ba83f622469b433f2cfea9e099c0d6a14192e8ab00f2fb7857f31c1b18aff1b1a42cc35945334735c28164b868cb90b2d5d2e6175473a705
+  data.tar.gz: 239ded33d2cb26e300ae0b6d7d8b071d84d7d5e205ade2a10c0bf443f599f201aecfb5a6fa7ddaa8523f312782d0e7bc864770da0d51fe1db35bcf2bb922d435

data/README.md

@@ -0,0 +1,38 @@
+# intranet-core
+
+`intranet-core` provides the core component of a generic, highly customizable
+intranet built around [WEBrick HTTP server](https://rubygems.org/gems/webrick).
+Each section of the intranet can be provided by a different _module_, which
+is basically a Webrick servlet in charge of a specific subdirectory of the
+web server.
+
+## Usage
+
+### Creating a custom _module_
+
+You can create a new _module_ by deriving from `Intranet::AbstractResponder`:
+
+```ruby
+require 'intranet/abstract_responder'
+
+class MyModule << Intranet::AbstractResponder
+  def initialize(params = {})
+    @params = params
+  end
+
+  def generate_page(path, query)
+    # generate HTML for the given path
+  end
+end
+```
+
+### Starting the Intranet
+
+The Intranet is controlled by the `Intranet::Core` class.
+
+```ruby
+intranet = Intranet::Core.new
+module = MyModule.new
+intranet.register_module(module, 'my_module', __dir__)
+intranet.start
+```

data/lib/core_extensions.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative 'core_extensions/string'
+require_relative 'core_extensions/tree'
+require_relative 'core_extensions/webrick/httpresponse'
+
+String.include CoreExtensions::String
+WEBrick::HTTPResponse.include CoreExtensions::WEBrick::HTTPResponse
+
+# @!visibility protected
+module CoreExtensions
+end

data/lib/core_extensions/string.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module CoreExtensions
+  # @!visibility protected
+  # Extension of Ruby's standard library +String+ class.
+  module String
+    # Replaces all accented characters in a string with their non-accented version.
+    # @return [String]
+    def unaccentize # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+      tr('ÀÁÂÃÄÅàáâãäåĀāĂ㥹',       'AAAAAAaaaaaaAaAaAa')
+        .tr('ÇçĆćĈĉĊċČčÐðĎďĐđ',      'CcCcCcCcCcDdDdDd')
+        .tr('ÈÉÊËèéêëĒēĔĕĖėĘęĚě',    'EEEEeeeeEeEeEeEeEe')
+        .tr('ĜĝĞğĠġĢģĤĥĦħ',          'GgGgGgGgHhHh')
+        .tr('ÌÍÎÏìíîïĨĩĪīĬĭĮįİı',    'IIIIiiiiIiIiIiIiIi')
+        .tr('ĴĵĶķĸĹĺĻļĽľĿŀŁł',       'JjKkkLlLlLlLlLl')
+        .tr('ÑñŃńŅņŇňʼnŊŋ',           'NnNnNnNnnNn')
+        .tr('ÒÓÔÕÖØòóôõöøŌōŎŏŐő',    'OOOOOOooooooOoOoOo')
+        .tr('ŔŕŖŗŘřŚśŜŝŞşŠšſŢţŤťŦŧ', 'RrRrRrSsSsSsSssTtTtTt')
+        .tr('ÙÚÛÜùúûüŨũŪūŬŭŮůŰűŲų',  'UUUUuuuuUuUuUuUuUuUu')
+        .tr('ŴŵÝýÿŶŷŸŹźŻżŽž',        'WwYyyYyYZzZzZz')
+        .gsub(/ß/, 'ss')
+        .gsub(/Æ/, 'AE')
+        .gsub(/æ/, 'ae')
+        .gsub(/Œ/, 'OE')
+        .gsub(/œ/, 'oe')
+        .gsub(/IJ/, 'IJ')
+        .gsub(/ij/, 'ij')
+    end
+
+    # Converts a string to a snake-cased format suitable for URL and/or CSS attributes.
+    # @return [String]
+    def urlize
+      strip.unaccentize.downcase.tr(' \'', '_').delete('^-_a-z0-9')
+    end
+
+    # Tests whether a string is urlize-d, ie. it is only constituted of characters suitable for URL
+    # and/or CSS attributes.
+    # @return [Boolean]
+    def urlized?
+      scan(/[^-_a-z0-9]/).empty?
+    end
+  end
+end

data/lib/core_extensions/tree.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module CoreExtensions
+  # N-ary tree data structure.
+  # Each node of the tree contains an +Object+ (the node value) and can be accessed from its parent
+  # node using an identifier +Object+. A node can be identified uniquely by the succession of
+  # identifiers that lead from the tree root to itself.
+  class Tree
+    # The value of the current tree node.
+    attr_accessor :value
+
+    # The child nodes of the current tree node.
+    # @return [Hash]
+    attr_reader :children_nodes
+
+    # Creates a new tree with a root element and no child nodes.
+    # @param node_value [Object] The value associated to the root element
+    def initialize(node_value = nil)
+      @value = node_value
+      @children_nodes = {}
+    end
+
+    # Queries
+
+    # Check if the current Tree node has children.
+    def children?
+      !@children_nodes.empty?
+    end
+
+    # Tests whether the current tree node has a specific child.
+    # @param child_id [Object] The unique identifier of the child.
+    # @return [Boolean] True if the child node identified by +child_id+ exists, False otherwise.
+    def child_exists?(child_id)
+      child_node(child_id)
+      true
+    rescue KeyError
+      false
+    end
+
+    # Retrieves the child of the current tree node.
+    # @param child_id [Object] The unique identifier of the child.
+    # @return [Object] The node value of the child identified by +child_id+.
+    # @raise [KeyError] If the child node identified by +child_id+ does not exist.
+    def child_node(child_id)
+      @children_nodes.fetch(child_id)
+    end
+
+    # Returns a hash representation of the current tree node and all its children, recursively
+    # (depth-first).
+    # @param separator [String] The separator to be used between node identifiers.
+    # @return [Hash]
+    def to_h(separator = '/', id_prefix = '')
+      hash = {}
+      id_prefix.empty? ? hash[separator] = @value : hash[id_prefix] = @value
+      @children_nodes.each do |id, node|
+        hash.merge!(node.to_h(separator, id_prefix + separator + id.to_s))
+      end
+      hash
+    end
+
+    # Returns the string representation of the current tree node and all its children, recursively
+    # (depth-first).
+    # @return [String]
+    def to_s(offset = '')
+      str = offset + 'VALUE: ' + @value.to_s + "\n"
+      @children_nodes.each do |id, node|
+        str += offset + ' * ID:   \'' + id.to_s + '\'' + "\n"
+        str += node.to_s(offset + '   ')
+      end
+      str
+    end
+
+    # Retrieves the value associated to a child node of the current tree node, inserting it first if
+    # it does not exist.
+    # @param child_id [Object] The unique identifier for the child node to retrieve or insert.
+    # @param child_value [Object] The value associated to the child node to insert. Ignored if a
+    #                             child node identified by the given +child_id+ already exists.
+    # @return [Object] The value associated to the child node identified by the given +child_id+.
+    def add_child_node(child_id, child_value = nil)
+      @children_nodes[child_id] = Tree.new(child_value) if @children_nodes[child_id].nil?
+      @children_nodes[child_id]
+    end
+  end
+end

data/lib/core_extensions/webrick/httpresponse.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'htmlentities'
+require 'webrick'
+require_relative '../../intranet/core/haml_wrapper'
+
+module CoreExtensions
+  # @!visibility protected
+  module WEBrick
+    # @!visibility protected
+    # Extension of +WEBrick::HTTPResponse+ to provide the hook
+    # +create_error_page+.
+    module HTTPResponse
+      include Intranet::Core::HamlWrapper
+
+      # Provides custom error pages for common HTTP errors.
+      def create_error_page
+        @body << to_markup('http_error', error: @status)
+      end
+    end
+  end
+end

data/lib/intranet/abstract_responder.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Intranet
+  # The default implementation and interface of an Intranet module.
+  class AbstractResponder
+    # Destroys the responder instance.
+    # This method gets called when server is shut down.
+    def finalize
+      # nothing to do
+    end
+
+    # Generates the HTML content associated to the given +path+ and +query+.
+    # @param path [String] The requested URI, relative to that module root URI
+    # @param query [Hash] The URI variable/value pairs, if any
+    # @return [Array] The HTTP return code, the MIME type and the answer body.
+    def generate_page(path, query)
+      [404, '', '']
+    end
+
+    # Provides the list of Cascade Style Sheets (CSS) dependencies for this module.
+    # If redefined, this method should probably append dependencies rather than overwriting them.
+    # @return [Array] The list of CSS dependencies, as URL path from server root
+    def css_dependencies
+      ['/design/style.css']
+    end
+
+    # Provides the list of Javascript files (JS) dependencies for this module.
+    # If redefined, this method should probably append dependencies rather than overwriting them.
+    # @return [Array] The list of JS dependencies, as URL path from server root
+    def js_dependencies
+      ['/design/nav.js']
+    end
+  end
+end

data/lib/intranet/core.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require 'webrick'
+require_relative 'logger'
+require_relative 'core/locales'
+require_relative 'core/haml_wrapper'
+require_relative 'core/builder'
+require_relative 'core/servlet'
+require_relative 'core/version'
+require_relative '../core_extensions'
+
+# The main Intranet namespace.
+module Intranet
+  # The core of the Intranet.
+  class Core
+    # The port currently used by the Intranet.
+    # @return [Integer]
+    attr_reader :port
+
+    # Initializes a new Intranet core instance. The first available port will be used, starting at
+    # +preferred_port+. If +preferred_port+ port is 80 and the user has not enough priviledges to
+    # use that port, port 8080 (or one of the following ports) will be used.
+    # @param logger [Object] The logger.
+    # @param preferred_port [Integer] The preferred port for the web server.
+    def initialize(logger, preferred_port = 80)
+      @logger = logger
+
+      # Initialize translation module
+      Intranet::Core::Locales.initialize
+
+      # Initialize HAML wrapper
+      Intranet::Core::HamlWrapper.initialize
+
+      # Instanciate Intranet Builder and register page builders
+      @builder = Intranet::Core::Builder.new(@logger)
+
+      # Instanciate WebRick HTTP server
+      @server = load_http_server(preferred_port)
+      www_dir = File.join(__dir__, 'resources', 'www')
+      mount_default_servlets(www_dir)
+    end
+
+    # Registers a new module to the core. The server must not be running. If +path+ is empty, the
+    # module will be used as Home module. Otherwise, the module will be accessible through the
+    # given +path+ under the web server root.
+    # @param responder [Intranet::AbstractResponder] The module responder instance.
+    # @param path [Array] The path, relative to the web server root, representing the module root
+    #                     directory. If empty, the responder will be registered as Home responder
+    #                     (to serve /index.html in particular). Subdirectories are allowed using
+    #                     an array element for each directory level. Each element must only contain
+    #                     the following characters: +-_a-z0-9+.
+    # @param resources_dir [String] The path to the directory that contains additional resources
+    #                               required by the module. This directory should contain three
+    #                               subdirectories: +haml/+, +locales/+ and +www/+.
+    # @raise [ArgumentError] If one of the element of the +path+ contains invalid characters.
+    # @raise [Errno::EALREADY] If the server is already running.
+    def register_module(responder, path, resources_dir)
+      raise ArgumentError unless path.all?(&:urlized?)
+      raise Errno::EALREADY if @server.status != :Stop
+
+      @builder.register(responder, path)
+      module_add_servlet(path.empty? ? ['home'] : path, resources_dir)
+      module_add_locales(resources_dir)
+      module_add_haml_templates(resources_dir)
+    end
+
+    # Starts the web server.
+    def start
+      @logger.info('Intranet::Core: using locale \'' + I18n.default_locale.to_s + '\'')
+      @logger.info('Intranet::Core: running Intranet version ' + VERSION)
+      # Start serving HTTP requests
+      @server.start
+    end
+
+    # Stops the web server and finalizes all registered module responders.
+    def stop
+      @logger.info('Intranet::Runner: requesting system shutdown...')
+      @server.shutdown
+      @builder.finalize
+      @logger.close
+    end
+
+    private
+
+    # See https://github.com/nahi/webrick/blob/master/lib/webrick/accesslog.rb#L69
+    ACCESSLOG_FMT = "%h '%r' -> %s (%b bytes in %Ts)"
+
+    def load_http_server(preferred_port)
+      @port = preferred_port
+      begin
+        WEBrick::HTTPServer.new(Port: @port, Logger: @logger, AccessLog: [[@logger, ACCESSLOG_FMT]])
+      rescue Errno::EACCES # not enough permission to use port 80
+        @port = 8080
+        retry
+      rescue Errno::EADDRINUSE
+        @port += 1
+        retry
+      end
+    end
+
+    def mount_default_servlets(www_dir)
+      # Configure handlers for HTTP server
+      # Start serving www/ as HTTP server root "/" using the class WEBrick::HTTPServlet::FileHandler
+      # You can write your own servlet (it must inherit from WEBrick::HTTPServlet::AbstractServlet)
+      # http://ruby-doc.org/stdlib-1.9.3/libdoc/webrick/rdoc/WEBrick/HTTPServlet/AbstractServlet.html
+      # https://www.igvita.com/2007/02/13/building-dynamic-webrick-servers-in-ruby/
+      @server.mount('/design', WEBrick::HTTPServlet::FileHandler, www_dir)
+      @server.mount('/', Intranet::Core::Servlet, @builder)
+    end
+
+    def module_add_servlet(path, resources_dir)
+      @server.mount('/design/' + path.join('/'),
+                    WEBrick::HTTPServlet::FileHandler,
+                    File.join(resources_dir, 'www'))
+    end
+
+    def module_add_locales(resources_dir)
+      Intranet::Core::Locales.add_path(File.join(resources_dir, 'locales'))
+    end
+
+    def module_add_haml_templates(resources_dir)
+      Intranet::Core::HamlWrapper.add_path(File.join(resources_dir, 'haml'))
+    end
+  end
+end

data/lib/intranet/core/builder.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative 'haml_wrapper'
+require_relative 'version'
+require_relative '../../core_extensions'
+
+module Intranet
+  class Core
+    # @!visibility protected
+    # Builder for the Intranet. The builder is in charge of storing registered modules (responders
+    # instances) and to call the appropriate responder according to the received URL.
+    class Builder
+      include HamlWrapper
+
+      # The tree-like structure containing all registered responders (for Haml)
+      # @return [CoreExtensions::Tree]
+      attr_reader :responders
+
+      # Initializes a new builder.
+      # @param logger [Object] The logger.
+      def initialize(logger)
+        @logger = logger
+        @responders = CoreExtensions::Tree.new
+      end
+
+      # Finalizes the builder. Each registered responder is called for +finalize+.
+      def finalize
+        @responders.to_h.each do |path, responder|
+          next if responder.nil?
+
+          @logger.debug('Intranet::Builder: finalize responder at \'' + path + '\'')
+          responder.finalize
+        end
+      end
+
+      # Processes the given URL path and query. The corresponding responder is called to get the
+      # page content. If no responder can handle the request, HTTP error 404 is returned. If the
+      # responder returns a partial HTML content (HTTP error 206), it is assumed to be the page
+      # body and integrated into the Intranet template.
+      # @param path [String] The requested path, relative to the web server root. This path is
+      #                      supposed secured and normalized (no '../' in particular).
+      # @param query [Hash] The content of the GET parameters of the URL.
+      # @return [Array] The HTTP return code, the MIME type and the answer body.
+      def do_get(path, query = {})
+        resp, responder_path = get_responder(path)
+        status, mime_type, body = resp.generate_page(responder_path, query)
+
+        # Generate header and footer when partial content is returned by the responder
+        if status == 206 && mime_type == 'text/html'
+          body = to_markup('skeleton', is_home: path == '/index.html', body: body,
+                                       css: resp.css_dependencies, js: resp.js_dependencies)
+          status = 200
+        end
+        [status, mime_type, body]
+      rescue KeyError, NoMethodError
+        [404, '', '']
+      end
+
+      # Registers a new responder. If a responder is already registered with the same path, the new
+      # one overrides the old one.
+      # @param responder [Intranet::AbstractResponder] The responder instance of the module.
+      # @param path [Array] The path, relative to the web server root, representing the module root
+      #                     directory. If empty, the responder will be registered as Home responder
+      #                     (to serve /index.html in particular). Subdirectories are allowed using
+      #                     an array element for each directory level.
+      # @raise [ArgumentError] If one of the element of the +path+ contains invalid characters.
+      def register(responder, path = [])
+        raise ArgumentError unless path.all?(&:urlized?)
+
+        current_node = @responders
+        path.each do |part|
+          next if part.empty? || part == '.'
+
+          current_node = current_node.add_child_node(part)
+        end
+        current_node.value = responder
+      end
+
+      private
+
+      # Get the responder instance associated with the given path.
+      # @param path [String] The absolute URL path.
+      # @return [Array] The responder instance (possibly nil) and the remaining of the URL path that
+      #                 has not been parsed.
+      def get_responder(path)
+        current_treenode = @responders
+        relative_path = path[1..-1].split('/').delete_if do |part|
+          if current_treenode.child_exists?(part)
+            current_treenode = current_treenode.child_node(part)
+            true
+          end
+        end
+
+        [current_treenode.value, '/' + relative_path.join('/')]
+      end
+    end
+  end
+end