simple-httpd 0.0.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3273a1672a08dca30bf4541e2169bee7e5eb107b0cbf4f335c20c5c4d2190756
-  data.tar.gz: c5262312bb70eb9e213688d6b85c05c4c1bd447d3e682eed5f1ba415d69a33b9
+  metadata.gz: e2cf16a40a84142155ccfdf2486e3f12d2a2be13429a942660136ba1c7ce5034
+  data.tar.gz: fe679b913fe4ea849945b797fd949ec4d4f9dc783d7ea252e358060037ec25e9
 SHA512:
-  metadata.gz: 44224855c4874348894465f0a56e4910a4d136a5fb675dd34dec7d4306affacdae9c161caccad1eb91122eddb9d1894811938c6f3888abba7e8090d8111d0657
-  data.tar.gz: 6b4bc045304a398031f17471d74c3dca151b0b7ae3847f859fbdf91e80777c9f77b10946f380ebf12e5946a9e6caca7f60a79cdd274ce593a8c25f00e41fb963
+  metadata.gz: 36e023782c8602e0864b1787ee661b1b4c6df8b76ea28889a14acc77116b927c98dd7d720850337b011a7c32ad6694767a776ba92ed772953ebdf3960ff43932
+  data.tar.gz: 0011d3b37a962c6dd5b1781f5dfd934aef319b8e13033b370fc9f4b240fa921ef06475808d7780072cd6c82675db95103d6c856911dd8a61d4048f8a45430bd3

data/.gitignore

@@ -1,7 +1,7 @@
 coverage
 rdoc
 pkg
-log/test.log
+log/*.log
 .rspec.data
 Gemfile.lock
 .rake_t_cache

data/.rubocop.yml

@@ -78,3 +78,12 @@ Style/TrailingUnderscoreVariable:
   
 Style/StderrPuts:
   Enabled: false
+
+Style/NonNilCheck:
+  Enabled: false
+
+Metrics/ParameterLists:
+  Enabled: false
+
+Style/StringLiteralsInInterpolation:
+  Enabled: false

data/.tm_properties

@@ -0,0 +1 @@
+excludeDirectories = "{_build,coverage,assets/node_modules,node_modules,deps,db,cover,priv/static,storage,github,vendor,arena,}"

data/Gemfile

@@ -1,5 +1,25 @@
 source 'https://rubygems.org'
 
-gem 'byebug'
 # Specify your gem's dependencies in {gemname}.gemspec
 gemspec
+
+# --- Local overrides for runtime dependencies ------------------------------
+
+# gem "simple-cli", path: "../simple-cli"
+
+# --- Development and test dependencies ------------------------------
+
+group :development, :test do
+  gem "rspec-httpd", "~> 0.3.0"
+  # gem "rspec-httpd", path: "../rspec-httpd"
+
+  gem 'rake', '~> 11'
+  gem 'rspec', '~> 3.7'
+  # gem 'rubocop', '~> 0.61.1'
+  gem 'simplecov', '~> 0'
+  gem 'byebug'
+
+  if ENV["PRELOAD_SERVER_GEM"]
+    gem ENV["PRELOAD_SERVER_GEM"]
+  end
+end

data/Makefile

@@ -0,0 +1,9 @@
+.PHONY: test
+
+test:
+	rspec
+
+.PHONY: fulltest
+fulltest:
+	rspec
+	PRELOAD_SERVER_GEM=puma rspec

data/README.md

@@ -1,3 +1,88 @@
-# simple-httpd
+# simple-httpd – serving HTTP made simpler.
 
-[TODO]
+This ruby gem wraps around [sinatra](/) to provide an even simpler way of setting up http based backends. It is especially helpful to:
+
+- bind loosely related pieces of code together: `simple-httpd` lets a developer lay out their code and assets in directories and trees of directories and can then serve these via HTTP.  
+- have an easy way to serve static assets via HTTP.
+- allow existing applications, especially CLI tools, to easily start HTTP servers.
+
+In some ways one might be reminded of the web's old days where one would throw a bunch of php scripts into a FTP location, and then an appache webserver (but, really, its php integration) would start serving requests via HTTPS. ***simple-httpd* is not like that.** This gem still supports the notion of an application; source files typically rely on other source files' existence and functionality.
+
+Also, at least as of now, **simple-httpd** does not dynamically reload code parts on request. This might change in the future.
+
+## Is it useful?
+
+At this point I don't know yet. We'll see. In any case this gem is used to test [rspec-httpd](github.com/radiospiel/rspec-httpd) (a rspec extension helping with testing HTTP endpoints), and is used within [postjob-httpd](github.com/radiospiel/postjob-httpd) where it is configured to glue HTTP endpoints to the [postjob](github.com/radiospiel/postjob) job queue system.
+
+It has proven useful so far - but as it is a really lean wrapper around sinatra one might probably also use sinatra in most cases.
+
+## Mounting directories
+
+`simple-httpd` lets a user of the gem "mount" directories onto "mount points". A "mount point" describes the location of the actions or static assets at the HTTP endpoint. Note that two or more directories can be mounted at the same mount point.
+
+Files in a mounted directory fall into different categories:
+
+### Static assets
+
+Static assets are files with a predefined set of file extensions, including `.txt` and `.js`. (compare the `static_mount.rb` source file for a full list.)
+
+They become available at the location specified by their filename and extension.
+
+### Dynamic assets
+
+Each mounted directory which contains ruby source files is converted into a sinatra application, which consists of a root configuration and controllers for each action file.
+
+Ruby files ending in `_helpers.rb`, e.g. `examples/ex1/ex1_helpers.rb` are executed in the context of a directory tree's root controller and provide functionality available in all action files. Typically they do not implement HTTP handlers themselves.
+
+All other ruby files implement HTTP handlers in typical sinatra fashion:
+
+    # in v2/jobs.rb
+    get "/queue/:id/events" do
+      events = [
+        { job_id: params[:id], id: "event1" },
+        { job_id: params[:id], id: "event2" }
+      ]
+    
+      json events
+    end
+
+If this snippet is contained in a file `v2/jobs.rb` and the `v2` directory is mounted into `api/v2`, the snipped implements the handler for, for example, `GET /api/v2/jobs/queue/123/events`. In other words, the handler implement in the source file works on paths relative to a path combining the mount location and the file name.
+
+To implement a action on the mountpoint itself one uses the `root.rb` file. The following
+
+    # in v2/root.rb
+    get "/" do
+      json version: "123"
+    end
+
+would implement `GET /api/v2`.
+
+## Command line usage
+
+`simple-httpd` comes with a CLI tool, which lets one assemble multiple locations into a single HTTP backend: the following command serves the *./ex1* and *./ex2* directories at `http://0.0.0.0:12345` and the *./v2* directory at `http://0.0.0.0:12345/api/v2`.
+
+    simple-httpd --port=12345 ex1 ex2 v2:api/v2
+
+The `v2:api/v2` argument asks the `v2` directory to be mounted into the web endpoint at `/api/v2`. All relevant content is therefore served below `http://0.0.0.0:12345/api/v2`.
+
+The arguments `ex1` and `ex2` serve at the `/` location. This notation really is a shorthand for `ex1:/` 
+
+## Integration
+
+`simple-httpd` can be integrated into other ruby scripts. Example:
+
+    require "simple-httpd"
+
+    httpd_root_dir = File.join(__dir__, "httpd")
+    port = 12345
+
+    app = ::Simple::Httpd.build("/" => httpd_root_dir)
+    ::Simple::Httpd.listen! app, port: port,
+                                 logger: ::Logger.new(STDERR)
+
+
+## The example application
+
+An example application is contained in ./examples. (Well, this example is probably not as *useful* for any purpose, but I hope it demonstrates all simple-httpd use cases, also it is used during tests.)
+
+See [its readme](examples/README.md) for more details.

data/Rakefile

@@ -1 +1,6 @@
 Dir.glob("tasks/*.rake").each { |r| import r }
+
+task :release do
+  sh "scripts/release"
+end
+

data/VERSION

@@ -1 +1 @@
-0.0.4
+0.3.0

data/bin/simple-httpd

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+$: << "lib"
+
+require "bundler"
+Bundler.setup
+
+# === setup and run Simple Httpd server =======================================
+require "simple/cli"
+require "simple/httpd/cli"
+
+# run the :main command with these arguments. This switches simple-cli into
+# non-subcommand mode.
+Simple::Httpd::CLI.run!(:main)

data/examples/README.md

@@ -0,0 +1,41 @@
+# An example
+
+This directory contains an example application. (Well, this example is probably not as *useful* for any purpose, but I hope it demonstrates all simple-httpd use cases, also it is used during tests.)
+
+See [its readme](examples/README.md) for more details.
+
+## How to start the example application
+
+Assuming you have installed the simple-httpd gem via `gem install simple-httpd` you should be able to start the server via
+
+    simple-httpd --port=12345 ex1 ex2 v2:api/v2
+
+This starts a HTTPD server on `http://0.0.0.0:12345`. The server serves content from the `./ex1` and `./ex2` directories at the root URL (`http://0.0.0.0:12345/`) and content from the ./v2 directory below `http://0.0.0.0:12345/api/v2`.
+
+The following explanations assume you started a server with the configuration mentioned above.
+
+## Files
+
+This directory currently contains these files:
+
+    - ex1/root.rb
+    - ex1/ex1_helpers.rb
+    - ex2/helpers.rb
+    - ex2/root.rb
+    - ex2/info.rb
+    - ex2/ex2_helpers.rb
+    - ex2/README.txt
+    - v2/root.rb
+    - v2/jobs.rb
+    - v2/v2_helpers.rb
+    - v2/api.js
+
+## Some routes
+
+The following lists some routes and where they are implemented:
+
+  GET "/"                         .. in ex1/root.rb
+  GET "/debug"                    .. in ex2/root.rb
+  GET "/info/inspect"             .. in ex2/info.rb
+  GET "/api/v2/"                  .. in v2/root.rb
+  GET "/api/v2/jobs/:id/events"   .. in v2/jobs.rb

data/examples/ex1/ex1_helpers.rb

@@ -0,0 +1,5 @@
+helpers do
+  def ex1_helper
+    "ex1_helper"
+  end
+end

data/examples/ex1/root.rb

@@ -0,0 +1,11 @@
+get "/" do
+  "root"
+end
+
+get "/hello" do
+  "hello"
+end
+
+get "/exit" do
+  exit 1
+end

data/examples/ex2/README.txt

@@ -0,0 +1 @@
+This is a README file

data/examples/ex2/ex2_helpers.rb

@@ -0,0 +1,5 @@
+helpers do
+  def ex2_helper
+    "ex2_helper"
+  end
+end

data/examples/ex2/helpers.rb

@@ -0,0 +1,15 @@
+get "/ex1" do
+  begin
+    ex1_helper
+  rescue NameError
+    not_found! "ex1_helper cannot be run"
+  end
+end
+
+get "/ex2" do
+  begin
+    ex2_helper
+  rescue NameError
+    not_found! "ex2_helper cannot be run"
+  end
+end

data/examples/ex2/info.rb

@@ -0,0 +1,4 @@
+get "/inspect" do
+  content_type :text
+  request.env.map { |key, value| "#{key}=#{value}\n" }.grep(/^[A-Z]/).sort.join
+end

data/examples/ex2/root.rb

@@ -0,0 +1,3 @@
+get "/debug" do
+  debug params
+end

data/examples/ex3/example_service.rb

@@ -0,0 +1,13 @@
+get "/check" do
+  "ok: explicit_service"
+end
+
+mount_service ExplicitService do |service|
+  # def echo(one, two, a:, b:)
+  post "/echo/:a" => :explicit_echo
+
+  put "/echo_context" do
+    # def echo_context
+    service.call(:echo_context, parsed_body, params, context: context)
+  end
+end

data/examples/services/example_service.rb

@@ -0,0 +1,25 @@
+# rubocop:disable Naming/UncommunicativeMethodParamName, Lint/UnusedMethodArgument
+
+module Example; end
+module Example::Service
+  include ::Simple::Service
+
+  def test(a:, b:)
+    # "this is a test; a is #{a.inspect}, b is #{b.inspect}"
+    "hello from ExampleService#test"
+  end
+
+  def echo(one, two, a:, b:)
+    "one: [#{one}]/two: [#{two}]/a: [#{a}]/b: [#{b}]"
+  end
+
+  def echo_context
+    ::Simple::Service.context.inspect
+  end
+
+  def this_is_a_helper!; end
+
+  private
+
+  def this_is_a_private_helper; end
+end

data/examples/services/explicit_example_service.rb

@@ -0,0 +1,18 @@
+# rubocop:disable Naming/UncommunicativeMethodParamName, Lint/UnusedMethodArgument
+
+module ExplicitService
+  include ::Simple::Service
+
+  def explicit_test(a:, b:)
+    # "this is a test; a is #{a.inspect}, b is #{b.inspect}"
+    "hello from ExplicitService#test"
+  end
+
+  def explicit_echo(one, two, a:, b:)
+    "one: [#{one}]/two: [#{two}]/a: [#{a}]/b: [#{b}]"
+  end
+
+  def echo_context
+    ::Simple::Service.context.inspect
+  end
+end

data/examples/v2/api.js

@@ -0,0 +1 @@
+/* API example file */

data/examples/v2/jobs.rb

@@ -0,0 +1,13 @@
+get "/info" do
+  content_type :text
+  "info"
+end
+
+get "/:id/events" do
+  events = [
+    { job_id: params[:id], id: "event1" },
+    { job_id: params[:id], id: "event2" }
+  ]
+
+  json events
+end

data/examples/v2/root.rb

@@ -0,0 +1,3 @@
+get "/" do
+  json version: "v2"
+end

data/examples/v2/v2_helpers.rb

@@ -0,0 +1,5 @@
+helpers do
+  def v2_helper
+    "v2_helper"
+  end
+end

data/lib/simple-service.rb

@@ -0,0 +1,3 @@
+# rubocop:disable Naming/FileName
+
+require "simple/service"

data/lib/simple/httpd.rb

@@ -1,43 +1,117 @@
+# rubocop:disable Style/TrivialAccessors
+
 module Simple
 end
 
-module Simple::Httpd
+class Simple::Httpd
 end
 
-require "simple/httpd/version"
-require "simple/httpd/app"
+require "simple/service"
+
+require "simple/httpd/helpers"
 require "simple/httpd/base_controller"
+require "simple/httpd/version"
+require "simple/httpd/mount_spec"
+require "simple/httpd/server"
 
-module Simple::Httpd
-  extend self
+require "simple/httpd/service"
+
+class Simple::Httpd
+  SELF = self
+
+  def self.logger=(logger)
+    @logger = logger
+  end
 
-  def build_rack(base_controller, logger:)
-    App.new(base_controller, logger: logger)
+  def self.logger
+    @logger ||= ::Logger.new(STDERR, level: ::Logger::INFO)
   end
 
-  def listen!(app, environment:, port:)
-    expect! port => 80..60_000
+  # Converts the passed in args into a Simple::Httpd application.
+  #
+  # The passed in arguments are used to create a Simple::Httpd object.
+  # If the function receives a rack app (determined by the ability to
+  # respond to call/3) it redirects to <tt>Server.listen!</tt> right
+  # away - this way this method can be used as a helper method
+  # to easily start a Rack server.
+  def self.listen!(*mount_specs, environment: "development", host: nil, port:, logger: nil, &block)
+    # If there is no argument but a block use the block as a rack server
+    if block
+      raise ArgumentError, "Can't deal w/block *and* mount_specs" unless mount_specs.empty?
 
-    logger = app.logger
-    logger.info "Starting httpd server on http://0.0.0.0:#{port}/"
+      app = block
+    elsif mount_specs.length == 1 && mount_specs.first.respond_to?(:call)
+      # there is one argument, and that looks like a Rack app: return that.
+      app = mount_specs.first
+    else
+      # Build a Httpd app, and listen
+      app = build(*mount_specs)
+      app.rack
+    end
 
-    app = Rack::Lint.new(app) if environment != "production"
+    Server.listen!(app, environment: environment, host: host, port: port, logger: logger)
+  end
+
+  # Converts the passed in arguments into a Simple::Httpd application.
+  #
+  # For a description of mounts see <tt>#add</tt>
+  def self.build(*mount_specs)
+    new(*mount_specs)
+  end
+
+  private
+
+  # Builds a Simple::Httpd application.
+  def initialize(*mount_specs)
+    @mount_specs = []
+    mount_specs.map do |mount_spec|
+      mount(mount_spec, at: nil)
+    end
+  end
+
+  public
+
+  # Adds one or more mount_points
+  #
+  # Each entry in mounts can be either:
+  #
+  # - a mount_point <tt>[ mount_point, path ]</tt>, e.g. <tt>[ "path/to/root", "/"]</tt>
+  # - a string denoting a mount_point, e.g. "path/to/root:/")
+  # - a string denoting a "/" mount_point (e.g. "path", which is shorthand for "path:/")
+  #
+  def mount(mount_spec, at: nil)
+    raise ArgumentError, "Cannot mount onto an already built app" if built?
+
+    @mount_specs << MountSpec.build(mount_spec, at: at)
+  end
+
+  extend Forwardable
+  delegate :call => :rack # rubocop:disable Style/HashSyntax
+
+  def rack
+    @rack ||= build_rack
+  end
+
+  private
+
+  def build_rack
+    uri_map = {}
+
+    @mount_specs.group_by(&:mount_point).map do |mount_point, mount_specs|
+      apps = mount_specs.map(&:build_rack_apps).flatten
+      uri_map[mount_point] = Rack.merge(apps)
+    end
+
+    ::Rack::URLMap.new(uri_map)
+  end
 
-    # re/AccessLog: the AccessLog setting points WEBrick's access logging to the
-    # NullLogger object.
-    #
-    # Instead we'll use a combination of Rack::CommonLogger (see Simple::Httpd.app),
-    # and sinatra's logger (see Simple::Httpd::BaseController).
-    Rack::Server.start app: app,
-                       Port: port,
-                       environment: environment,
-                       Logger: logger,
-                       AccessLog: [[NullLogger, ""]]
+  def built?
+    @rack != nil
   end
 
-  module NullLogger # :nodoc:
-    extend self
+  public
 
-    def <<(msg); end
+  def listen!(environment:, port:, logger:)
+    SELF.listen!(rack, environment: environment, port: port, logger: logger)
   end
 end