Ecosyste.ms: Awesome

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

Awesome Lists | Featured Topics | Projects

https://github.com/sugar-framework/plugs

A collection of Plug middleware for web applications
https://github.com/sugar-framework/plugs

Last synced: 8 days ago
JSON representation

A collection of Plug middleware for web applications

Awesome Lists containing this project

README 

        
# Plugs



## `Sugar.Plugs.HotCodeReload`



Used to add hot code reloading to a project, preventing the need to stop, recompile, and start your application to see your changes.



Use:



```elixir

defmodule MyRouter do

  use Plug.Router



  plug Sugar.Plugs.HotCodeReload



  plug :match

  plug :dispatch



  # Rest of router definition

  ...

end

```



## `Sugar.Plugs.EnsureAuthenticated`



Used to ensure that a user is currently logged on before proceeding through a Plug pipeline.  This is designed first and foremost for [Sugar](http://sugar-framework.github.io), but it can hypothetically work with any plug-based app (emphasis on "hypothetically").



### Setup



In your `router.ex`:



```elixir

defmodule MyApp.Router do

  use Sugar.Router



  plug :put_secret_key_base

  plug Plug.Session,

    store: :cookie,

    key: "_my_app_session",

    encryption_salt: "encryption salt",

    signing_salt: "signing salt",

    key_length: 64



  def put_secret_key_base(conn, _) do

    base = "some 64 character random string"

    put_in conn.secret_key_base, base

  end



  # ...



end

```



You'll also want a controller to present a login page and authenticate a user (and possibly act on `conn.params["return_to"]`; see below).



### Use



Add this to a controller you want authentication on:



```elixir

defmodule MyApp.Controllers.Foo do

  use Sugar.Controller



  plug Sugar.Plugs.EnsureAuthenticated



  # ...



end

```



If your controller has some actions that don't need authentication, then you can use `plug Sugar.Plugs.EnsureAuthenticated, except: [:foo, :bar]`.  Likewise, if your controller's actions mostly don't require authentication, you can use `plug Sugar.Plugs.EnsureAuthenticated, only: [:baz, :bat]`.  Only specify one or the other (`:only` *should* take precedence in the event that both are used).



### Configuration



`Sugar.Plugs.EnsureAuthenticated` defaults to expect the following:



* You have an Ecto repo at `MyApp.Repos.Main`

* You have a User model at `MyApp.Models.User`

* Users should be directed to your app's `/login` route if they're not currently logged in



The first two can be overridden by calling the plug as `plug Sugar.Plugs.EnsureAuthenticated, repo: My.Custom.Repo, model: My.Custom.Model` (should be self-explanatory).  The third can't be changed quite yet (TODO: add that configuration option), at least not without implementing a custom handler (see below).



#### `:return_to` (`:origin` or an explicit URL)



One can provide a `:return_to` option, which adds a query parameter (named `return_to` by default) to signal to a login page where the user should be redirected to after logging in.  The most automatic approach would be to set this to `:origin`, like so:



```elixir

plug Sugar.Plugs.EnsureAuthenticated, return_to: :origin

```



The above reads the connection's original path and sets `conn.params["return_to"]` automatically.



#### Custom Handler



By default, `Sugar.Plugs.EnsureAuthenticated` uses a built-in handler to check for authentication.  This handler is pretty minimal in terms of what it does:



* Checks to see if the controller action being run actually requires authentication (by checking `conn.private.action` for an action name); if not, then continues without doing anything else.

* Checks to see if there's a "user_id" session key (if not, then redirects to "/login")

* Fetches a `%MyApp.Models.User{}` (or the struct for whatever model you've configured) from `MyApp.Repos.Main` (or whatever repo you've configured); if it can't find a user, then redirects to "/login"

* Assigns the found user to the connection's `:current_user` (for use by other plugs, namely [Canary](https://github.com/cpjk/canary)), then continues on the pipeline



If you need to implement custom functionality (for example, if you're not using Sugar-compatible controllers, or if you're not using Ecto models), you can call `plug Sugar.Plugs.EnsureAuthenticated, handler: {MyApp.Auth.Handler, :verify}` (where `MyApp.Auth.Handler` is a module and `:verify` is the name of a function in that module; you could also do `handler: MyApp.Auth.Handler`, in which case the `:verify` function will be called).



In order to work, the handler must accept both a `%Plug.Conn{}` (i.e. a `conn` variable, like in a typical plug) and a `Map` containing the options passed to `EnsureAuthenticated`.  From here, you can implement whatever checks you need to perform.



### To Do



* Allow more things to be customized without having to implement a custom handler

* Move default values from hard-coded to `config.exs`-based configuration