Shard Detail

armature v0.1.5

Roda-inspired HTTP framework for Crystal, providing routing, sessions, forms, etc
crystal http http-server routing

Install & Use

Add the following code to your project's shard.yml under:

dependencies to use in production
- OR -
development_dependencies to use in development


armature:
  github: jgaskins/armature

Readme

Armature

Armature is an HTTP routing framework for Crystal.

Installation

  1. Add the dependency to your shard.yml:

    dependencies:
      armature:
        github: jgaskins/armature
    
  2. Run shards install

Usage

Armature has 2 primary components:

  • Armature::Route
    • Provides a routing graph by allowing a top-level application to delegate to various child routes based on path segments
    • Provides an ECR rendering macro to render view templates at compile time. View templates are under the views/ directory in the application root.
    • Provides a missed-match handler (r.miss) so you can provide custom 404 handling in a way that's simple and discoverable
  • Armature::Session
    • If you're using cookie-based authentication, you can use Armature sessions to persist session data between requests
    • Currently the only supported session adapter is Armature::Session::RedisStore. The value stored in the cookie is the session id and the data stored in Redis will be the session data serialized into a JSON string.
require "armature"
require "armature/redis_session"
require "redis"

class App
  include HTTP::Handler
  include Armature::Route

  def call(context)
    route context do |r, response, session|
      # The `session` can be treated as a key/value object. All JSON-friendly
      # types can be stored and retrieved. The stored session data is saved as
      # JSON and parsed into a `JSON::Any`.
      if current_user_id = session["user_id"]?.try(&.as_i?)
        current_user = UserQuery.new.find_by_id(current_user_id)
      end

      # `render` macro provided by `Armature::Route` renders the given template
      # inside the `views/` directory to the `response` object. This example
      # renders `views/app_header.ecr`.
      #
      # Note: You can render as many templates as you need, allowing for nesting
      # your UI via nested routes.
      render "app_header"
      
      # Root path (all HTTP verbs)
      r.root do
        # Execute the given block only for GET requests
        r.get { render "homepage" }

        # Execute the given block only for POST requests
        r.post do
          # ...
        end
      end

      # Delegate certain paths to other `Armature::Route`s with `on`
      r.on "products" { Products.new.call(context) }

      # Allow for authenticated-only routes
      if current_user
        r.on "notifications" { Notifications.new(current_user).call(context) }
        r.on "cart" { Cart.new(current_user).call(context) }
      end

      # Execute a block if an endpoint has not been reached yet.
      r.miss do
        response.status = :not_found
        render "not_found"
      end

      # Rendering the footer below main app content
      render "app_footer"
    end
  end
end

http = HTTP::Server.new([
  Armature::Session::RedisStore.new(
    # the HTTP cookie name to store the session id in
    key: "app_session",
    # a client for the Redis instance to store session data in
    redis: Redis::Client.from_env("REDIS_URL"),
  ),
  App.new,
])
http.listen 8080

Other useful components are:

  • Armature::Form::Helper
  • Armature::Cache
  • Armature::Component

Contributing

  1. Fork it (https://github.com/jgaskins/armature/fork)
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

Contributors