Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jgaskins/armature

Roda-inspired HTTP framework for Crystal, providing routing, sessions, forms, etc
https://github.com/jgaskins/armature

crystal http http-server routing

Last synced: about 2 months ago
JSON representation

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

Awesome Lists containing this project

README 

        
# Armature



Armature is an HTTP routing framework for Crystal.



## Installation



1. Add the dependency to your `shard.yml`:



   ```yaml

   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](https://crystal-lang.org/api/1.0.0/ECR.html) 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.



```crystal

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 ()

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



- [Jamie Gaskins](https://github.com/jgaskins) - creator and maintainer