Skip to content

Commit

Permalink
Update for Crystal 0.20.0
Browse files Browse the repository at this point in the history
  • Loading branch information
sdogruyol committed Nov 24, 2016
1 parent 21d4f1a commit 5f267c4
Show file tree
Hide file tree
Showing 4 changed files with 15 additions and 56 deletions.
2 changes: 0 additions & 2 deletions .travis.yml
Original file line number Diff line number Diff line change
@@ -1,3 +1 @@
language: crystal
notifications:
email: false
65 changes: 13 additions & 52 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,24 +1,23 @@
# kemal-session

This project wants to be a session plugin for [Kemal](https://github.com/sdogruyol/kemal) when it grows up. It is still in alpha stage but it works! ;-)
Session support for [Kemal](https://github.com/sdogruyol/kemal) :rocket:

## Installation


Add this to your application's `shard.yml`:

```yaml
dependencies:
kemal-session:
github: Thyra/kemal-session
github: kemalcr/kemal-session
branch: master
```
## Usage
### Basic Usage
Create a folder ```sessions``` in the same directory that your webserver is running in and make sure the webserver process has write privileges to it.
```crystal
require "kemal"
require "kemal-session"
Expand All @@ -38,45 +37,13 @@ Kemal.run
```
The session can save Int32, String, Float64 and Bool values. Use ```session.int```, ```session.string```, ```session.float``` and ```session.bool``` for that.

Another example
```crystal
require "kemal"
require "kemal-session"
get "/rand" do |env|
if env.session.int? "random_number"
env.response.print "The last random number was #{env.session.int("random_number")}. "
else
env.response.print "This is the first random number. "
end
random_number = rand(500)
env.session.int("random_number", random_number)
env.response.print "Setting the random number to #{random_number}"
end
get "/set" do |env|
env.session.string(env.params.query["key"].to_s, env.params.query["value"].to_s)
"Setting <i>#{env.params.query["key"]}</i> to <i>#{env.params.query["value"]}</i>"
end
get "/get" do |env|
if env.session.string? env.params.query["key"].to_s
"The value of #{env.params.query["key"]} is #{env.session.string(env.params.query["key"].to_s)}"
else
"There is no value for this key."
end
end
Kemal.run
```
Open ```/set?key=foo&value=bar``` to set the value of *foo* to *bar* in your session. Then open ```/get?key=foo``` to retrieve it.

You can also access the underyling hash directly by appending ``s`` to the name: ``session.ints``. This way you can use hash functions like
```crystal
session.ints.each do |k, v|
puts "#{k} => #{v}"
end
```

**BUT:** This should only be used for reading and analyzing values, **never for changing them**. Because otherwise the session won't automatically save the changes and you may produce really weird bugs...

### Configuration
Expand All @@ -101,26 +68,20 @@ Session.config.cookie_name = "foobar"
| gc_interval | In which interval should the garbage collector find and delete expired sessions from the server? | ```Time::Span.new(0, 4, 0)``` (4 minutes) |

#### Setting the Engine
The Engine takes care of actually saving the sessions on the server. The standard engine is the FileSystemEngine which creates a json file for each session in a certain folder on the file system. Theoretically there are innumerable possible engines; any way of storing and retrieving values could be used:
* Storing the values in a database (MySQL, SQLite, MongoDB etc.)
* Storing the values in RAM (e.g. like Redis)
* Saving and retreiving the values from a remote server via an API
* Printing on paper, rescanning and running an OCR on it.
The standard engine is the MemoryEngine

The engine you use has a huge impact on performance and can enable you to share sessions between different servers, make them available to any other application or whatever you can imagine. So the choice of engine is very important. Luckily for you, there is only one engine available right now ;-): The FileSystemEngine. It is set by default to store all the session in a folder called sessions in the directory the server is running in. If you want to save them someplace else, just use this:
The engine you use has a huge impact on performance and can enable you to share sessions between different servers, make them available to any other application or whatever you can imagine. So the choice of engine is very important.

```crystal
Session.config.engine = Session::FileSystemEngine.new({sessions_dir: "/var/foobar/sessions/"})
```
You can also write your own engine if you like. Take a look at the [wiki page](https://github.com/Thyra/kemal-session/wiki/Creating-your-own-engine). If you think it might also be helpful for others just let me know about it and I will include it in a list of known engines or something.
You can also write your own engine if you like. Take a look at the [wiki page](https://github.com/kemalcr/kemal-session/wiki/Creating-your-own-engine). If you think it might also be helpful for others just let me know about it and I will include it in a list of known engines or something.

### Features already implemented
- storing of Int32, String, Float64 and Bool values
- a garbage collector that removes expired sessions from the server
- a filesystem engine (saves sessions on the file system)

### Features in development
- storing of more data types, including arrays and possibly hashes
- engines for memory (sessions are stored in process memory), mysql and postregsql (sessions are stored in database)
- secure session id against brute force attacks by binding it to ip adress and user agent
- Storing of Int32, String, Float64 and Bool values
- Garbage collector that removes expired sessions from the server
- Memory engine

### Roadmap
- More data types, including arrays and possibly hashes
- Manage sessions: Session.all, Session.remove(id), Session.get(id)...
2 changes: 1 addition & 1 deletion shard.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ name: kemal-session
version: 0.1.0

authors:
- Thyra <Thyra@users.noreply.github.com>
- Serdar Dogruyol <dogruyolserdar@gmail.com>

development_dependencies:
kemal:
Expand Down
2 changes: 1 addition & 1 deletion spec/spec_helper.cr
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ require "../src/kemal-session"
require "file_utils"

def create_context(session_id : String)
response = HTTP::Server::Response.new(MemoryIO.new)
response = HTTP::Server::Response.new(IO::Memory.new)
headers = HTTP::Headers.new

# I would rather pass nil if no cookie should be created
Expand Down

0 comments on commit 5f267c4

Please sign in to comment.