Skip to content

Commit 3eeb885

Browse files
mullermpmullermp
authored
Merge pull request #1 from aws/init
Initial commit of aws-actiondispatch-dynamodb
2 parents 7548519 + b2f2cec commit 3eeb885

35 files changed

+1005
-9
lines changed

‎.github/PULL_REQUEST_TEMPLATE.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
*Issue #, if available:*
2+
3+
*Description of changes:*
4+
5+
By submitting this pull request, I confirm that my contribution is made under
6+
the terms of the Apache 2.0 license.

‎.github/workflows/ci.yml

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
8+
pull_request:
9+
branches:
10+
- main
11+
12+
env:
13+
ruby_version: 3.3
14+
15+
jobs:
16+
test:
17+
runs-on: ubuntu-latest
18+
strategy:
19+
fail-fast: false
20+
matrix:
21+
ruby: [2.7, '3.0', 3.1, 3.2, 3.3, jruby-9.4]
22+
rails: [7.1, 7.2, '8.0', main]
23+
24+
exclude:
25+
# Rails 7.2 is Ruby >= 3.1
26+
- rails: 7.2
27+
ruby: 2.7
28+
- rails: 7.2
29+
ruby: 3.0
30+
# Rails 8.0 is Ruby >= 3.2
31+
- rails: '8.0'
32+
ruby: 2.7
33+
- rails: '8.0'
34+
ruby: 3.0
35+
- rails: '8.0'
36+
ruby: 3.1
37+
- rails: '8.0'
38+
ruby: jruby-9.4
39+
# Rails main is Ruby >= 3.2
40+
- rails: main
41+
ruby: 2.7
42+
- rails: main
43+
ruby: 3.0
44+
- rails: main
45+
ruby: 3.1
46+
- rails: main
47+
ruby: jruby-9.4
48+
49+
steps:
50+
- uses: actions/checkout@v4
51+
52+
- name: Setup Ruby
53+
uses: ruby/setup-ruby@v1
54+
with:
55+
ruby-version: ${{ matrix.ruby }}
56+
bundler-cache: true
57+
58+
- name: Install gems
59+
run: bundle install
60+
env:
61+
BUNDLE_GEMFILE: gemfiles/rails-${{ matrix.rails }}.gemfile
62+
63+
- name: Test
64+
run: bundle exec rake test
65+
env:
66+
BUNDLE_GEMFILE: gemfiles/rails-${{ matrix.rails }}.gemfile
67+
68+
rubocop:
69+
runs-on: ubuntu-latest
70+
71+
steps:
72+
- uses: actions/checkout@v4
73+
74+
- name: Setup Ruby
75+
uses: ruby/setup-ruby@v1
76+
with:
77+
ruby-version: ${{ env.ruby_version }}
78+
79+
- name: Install gems
80+
run: |
81+
bundle config set --local with 'development'
82+
bundle install
83+
84+
- name: Rubocop
85+
run: bundle exec rake rubocop

‎.gitignore

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
.idea/
2+
Gemfile.lock
3+
gemfiles/*.gemfile.lock
4+
5+
test/dummy/db/migrate
6+
test/dummy/log/

‎.gitmodules

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
[submodule "tasks/release"]
2+
path = tasks/release
3+
url = https://github.com/aws/aws-sdk-ruby-release-tools

‎.rubocop.yml

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
AllCops:
2+
NewCops: enable
3+
TargetRubyVersion: 2.7
4+
SuggestExtensions: false
5+
6+
Gemspec/RequireMFA:
7+
Enabled: false
8+
9+
Metrics/BlockLength:
10+
Exclude:
11+
- 'spec/**/*.rb'
12+
13+
Naming/FileName:
14+
Exclude:
15+
- 'gemfiles/*.gemfile'
16+
- 'lib/aws-actiondispatch-dynamodb.rb'

‎CHANGELOG.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Unreleased Changes
2+
------------------
3+
4+
* Feature - Initial version of this gem.

‎Gemfile

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# frozen_string_literal: true
2+
3+
source 'https://rubygems.org'
4+
5+
gemspec
6+
7+
gem 'rake', require: false
8+
9+
group :development do
10+
gem 'byebug', platforms: :ruby
11+
gem 'rubocop'
12+
end
13+
14+
group :test do
15+
gem 'minitest-spec-rails'
16+
end
17+
18+
group :docs do
19+
gem 'yard'
20+
gem 'yard-sitemap', '~> 1.0'
21+
end
22+
23+
group :release do
24+
gem 'octokit'
25+
end

‎README.md

Lines changed: 156 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,164 @@
1-
## My Project
1+
# ActionDispatch Session Storage with Amazon DynamoDB
22

3-
TODO: Fill this README out!
3+
[![Gem Version](https://badge.fury.io/rb/aws-actiondispatch-dynamodb-ruby.svg)](https://badge.fury.io/rb/aws-actiondispatch-dynamodb-ruby)
4+
[![Build Status](https://github.com/aws/aws-actiondispatch-dynamodb-ruby/workflows/CI/badge.svg)](https://github.com/aws/aws-actiondispatch-dynamodb-ruby/actions)
5+
[![Github forks](https://img.shields.io/github/forks/aws/aws-actiondispatch-dynamodb-ruby.svg)](https://github.com/aws/aws-actiondispatch-dynamodb-ruby/network)
6+
[![Github stars](https://img.shields.io/github/stars/aws/aws-actiondispatch-dynamodb-ruby.svg)](https://github.com/aws/aws-actiondispatch-dynamodb-ruby/stargazers)
47

5-
Be sure to:
8+
This gem contains an
9+
[ActionDispatch AbstractStore](https://api.rubyonrails.org/classes/ActionDispatch/Session/AbstractStore.html)
10+
implementation that uses Amazon DynamoDB as a session store, allowing access
11+
to sessions from other applications and devices.
612

7-
* Change the title in this README
8-
* Edit your repository description on GitHub
13+
## Installation
914

10-
## Security
15+
Add this gem to your Rails project's Gemfile:
1116

12-
See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
17+
```ruby
18+
gem 'aws-sdk-rails', '~> 4'
19+
gem 'aws-actiondispatch-dynamodb', '~> 0'
20+
```
1321

14-
## License
22+
Then run `bundle install`.
1523

16-
This project is licensed under the Apache-2.0 License.
24+
This gem also brings in the following AWS gems:
1725

26+
* `aws-sessionstore-dynamodb` -> `aws-sdk-dynamodb`
27+
28+
You will have to ensure that you provide credentials for the SDK to use. See the
29+
latest [AWS SDK for Ruby Docs](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/index.html#Configuration)
30+
for details.
31+
32+
If you're running your Rails application on Amazon EC2, the AWS SDK will
33+
check Amazon EC2 instance metadata for credentials to load. Learn more:
34+
[IAM Roles for Amazon EC2](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html)
35+
36+
## Usage
37+
38+
To use the session store, add or edit your
39+
`config/initializers/session_store.rb` file:
40+
41+
```ruby
42+
options = { table_name: '_your_app_session' }
43+
Rails.application.config.session_store :dynamo_db_store, **options
44+
```
45+
46+
You can now start your Rails application with DynamoDB session support.
47+
48+
**Note**: You will need a DynamoDB table to store your sessions. You can create
49+
the table using the provided Rake tasks or ActiveRecord migration generator
50+
after configuring.
51+
52+
## Configuration
53+
54+
You can configure the session store with code, ENV, or a YAML file, in this
55+
order of precedence. To configure in code, you can directly pass options to your
56+
`config/initializers/session_store.rb` file like so:
57+
58+
```ruby
59+
options = {
60+
table_name: 'your-table-name',
61+
table_key: 'your-session-key',
62+
dynamo_db_client: Aws::DynamoDB::Client.new(region: 'us-west-2')
63+
}
64+
Rails.application.config.session_store :dynamo_db_store, **options
65+
```
66+
67+
The session store inherits from the
68+
[`Rack::Session::Abstract::Persisted`](https://rubydoc.info/github/rack/rack-session/main/Rack/Session/Abstract/Persisted)
69+
class, which also supports additional options (such as `:key`).
70+
71+
For more information about this feature and configuration options, see the
72+
[Configuration](https://docs.aws.amazon.com/sdk-for-ruby/aws-sessionstore-dynamodb/api/Aws/SessionStore/DynamoDB/Configuration.html)
73+
class and the
74+
[GitHub repository](https://github.com/aws/aws-sessionstore-dynamodb-ruby).
75+
76+
### Configuration file generator
77+
78+
You can generate a configuration file for the session store using the following
79+
command (--environment=<environment> is optional):
80+
81+
```bash
82+
rails generate dynamo_db:session_store_config --environment=<Rails.env>
83+
```
84+
85+
The session store configuration generator command will generate a YAML file
86+
`config/aws_dynamo_db_session_store.yml` with default options. If provided an
87+
environment, the file will be named
88+
`config/aws_dynamo_db_session_store/<Rails.env>.yml`, which takes precedence
89+
over the default file.
90+
91+
## Migration
92+
93+
### ActiveRecord Migration generator
94+
95+
You can generate a migration file for the session table using the following
96+
command (<MigrationName> is optional):
97+
98+
```bash
99+
rails generate dynamo_db:session_store_migration <MigrationName>
100+
```
101+
102+
The session store migration generator command will generate a
103+
migration file `db/migration/#{VERSION}_#{MIGRATION_NAME}.rb`.
104+
105+
The migration file will create and delete a table with default options. These
106+
options can be changed prior to running the migration either by changing the
107+
configuration in the initializer, editing the migration file, in ENV, or in the
108+
config YAML file. These options are documented in the
109+
[Table](https://docs.aws.amazon.com/sdk-for-ruby/aws-sessionstore-dynamodb/api/Aws/SessionStore/DynamoDB/Table.html)
110+
class.
111+
112+
To create the table, run migrations as normal with:
113+
114+
```bash
115+
rails db:migrate
116+
```
117+
118+
To delete the table and rollback, run the following command:
119+
120+
```bash
121+
rails db:migrate:down VERSION=<VERSION>
122+
```
123+
124+
### Migration Rake tasks
125+
126+
If you are not using ActiveRecord, you can manage the table using the provided
127+
Rake tasks:
128+
129+
```bash
130+
rake dynamo_db:session_store:create_table
131+
rake dynamo_db:session_store:delete_table
132+
```
133+
134+
The rake tasks will create and delete a table with default options. These
135+
options can be changed prior to running the task either by changing the
136+
configuration in the initializer, in ENV, or in the config YAML file. These
137+
options are documented in the
138+
[Table](https://docs.aws.amazon.com/sdk-for-ruby/aws-sessionstore-dynamodb/api/Aws/SessionStore/DynamoDB/Table.html)
139+
class.
140+
141+
## Cleaning old sessions
142+
143+
By default sessions do not expire. You can use `:max_age` and `:max_stale` to
144+
configure the max age or stale period of a session.
145+
146+
You can use the DynamoDB
147+
[Time to Live (TTL) feature](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/TTL.html)
148+
on the `expire_at` attribute to automatically delete expired items, saving you
149+
the trouble of manually deleting them and reducing costs.
150+
151+
If you wish to delete old sessions based on creation age (invalidating valid
152+
sessions) or if you want control over the garbage collection process, you can
153+
use the provided Rake task:
154+
155+
```bash
156+
rake dynamo_db:session_store:clean
157+
```
158+
159+
The rake task will clean the table with default options. These options can be
160+
changed prior to running the task either by changing the configuration in the
161+
initializer, in ENV, or in the config YAML file. These options are documented in
162+
the
163+
[GarbageCollector](https://docs.aws.amazon.com/sdk-for-ruby/aws-sessionstore-dynamodb/api/Aws/SessionStore/DynamoDB/GarbageCollector.html)
164+
class.

‎Rakefile

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# frozen_string_literal: true
2+
3+
require 'rake/testtask'
4+
require 'rubocop/rake_task'
5+
6+
Dir.glob('tasks/**/*.rake').each do |task_file|
7+
load task_file
8+
end
9+
10+
RuboCop::RakeTask.new
11+
12+
Rake::TestTask.new do |t|
13+
t.libs << 'test'
14+
t.pattern = 'test/**/*_test.rb'
15+
t.warning = false
16+
end
17+
18+
task 'release:test' => :test

‎VERSION

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
0.1.0

‎aws-actiondispatch-dynamodb.gemspec

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# frozen_string_literal: true
2+
3+
version = File.read(File.expand_path('VERSION', __dir__)).strip
4+
5+
Gem::Specification.new do |spec|
6+
spec.name = 'aws-actiondispatch-dynamodb'
7+
spec.version = version
8+
spec.author = 'Amazon Web Services'
9+
spec.email = ['[email protected]']
10+
spec.summary = 'ActionDispatch integration with DynamoDB'
11+
spec.description = 'Amazon Dynamo DB as an ActionDispatch session store'
12+
spec.homepage = 'https://github.com/aws/aws-actiondispatch-dynamodb-ruby'
13+
spec.license = 'Apache-2.0'
14+
spec.files = Dir['LICENSE', 'CHANGELOG.md', 'VERSION', 'lib/**/*']
15+
16+
spec.add_dependency('actionpack', '>= 7.1.0')
17+
spec.add_dependency('aws-sessionstore-dynamodb', '~> 3')
18+
19+
spec.required_ruby_version = '>= 2.7'
20+
end

‎gemfiles/rails-7.1.gemfile

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# frozen_string_literal: true
2+
3+
eval_gemfile '../Gemfile'
4+
5+
gem 'rails', '~> 7.1.0'

‎gemfiles/rails-7.2.gemfile

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# frozen_string_literal: true
2+
3+
eval_gemfile '../Gemfile'
4+
5+
gem 'rails', '~> 7.2.0'

‎gemfiles/rails-8.0.gemfile

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# frozen_string_literal: true
2+
3+
eval_gemfile '../Gemfile'
4+
5+
gem 'rails', '~> 8.0.0'

‎gemfiles/rails-main.gemfile

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# frozen_string_literal: true
2+
3+
eval_gemfile '../Gemfile'
4+
5+
gem 'rails', github: 'rails/rails'

0 commit comments

Comments
 (0)