README.md
1[](https://circleci.com/gh/johannesboyne/gofakes3)
2[](https://codecov.io/gh/johannesboyne/gofakes3)
3
4
5# AWS (GOFAKE)S3
6
7AWS S3 fake server and testing library for extensive S3 test integrations.
8Either by running a test-server, e.g. for testing of AWS Lambda functions
9accessing S3. Or, to have a simple and convencience S3 mock- and test-server.
10
11## What to use it for?
12
13We're using it for the local development of S3 dependent Lambda functions,
14to test AWS S3 golang implementations and access, and
15to test browser based direct uploads to S3 locally.
16
17
18## What not to use it for?
19
20Please don't use gofakes3 as a production service. The intended use case for
21gofakes3 is currently to facilitate testing. It's not meant to be used for
22safe, persistent access to production data at the moment.
23
24There's no reason we couldn't set that as a stretch goal at a later date, but
25it's a long way down the road, especially while we have so much of the API left
26to implement; breaking changes are inevitable.
27
28In the meantime, there are more battle-hardened solutions for production
29workloads out there, some of which are listed in the "Similar Notable Projects"
30section below.
31
32
33## How to use it?
34
35### Example
36
37```golang
38// fake s3
39backend := s3mem.New()
40faker := gofakes3.New(backend)
41ts := httptest.NewServer(faker.Server())
42defer ts.Close()
43
44// configure S3 client
45s3Config := &aws.Config{
46 Credentials: credentials.NewStaticCredentials("YOUR-ACCESSKEYID", "YOUR-SECRETACCESSKEY", ""),
47 Endpoint: aws.String(ts.URL),
48 Region: aws.String("eu-central-1"),
49 DisableSSL: aws.Bool(true),
50 S3ForcePathStyle: aws.Bool(true),
51}
52newSession := session.New(s3Config)
53
54s3Client := s3.New(newSession)
55cparams := &s3.CreateBucketInput{
56 Bucket: aws.String("newbucket"),
57}
58
59// Create a new bucket using the CreateBucket call.
60_, err := s3Client.CreateBucket(cparams)
61if err != nil {
62 // Message from an error.
63 fmt.Println(err.Error())
64 return
65}
66
67// Upload a new object "testobject" with the string "Hello World!" to our "newbucket".
68_, err = s3Client.PutObject(&s3.PutObjectInput{
69 Body: strings.NewReader(`{"configuration": {"main_color": "#333"}, "screens": []}`),
70 Bucket: aws.String("newbucket"),
71 Key: aws.String("test.txt"),
72})
73
74// ... accessing of test.txt through any S3 client would now be possible
75```
76
77Please feel free to check it out and to provide useful feedback (using github
78issues), but be aware, this software is used internally and for the local
79development only. Thus, it has no demand for correctness, performance or
80security.
81
82There are two ways to run locally: using DNS, or using S3 path mode.
83
84S3 path mode is the most flexible and least restrictive, but it does require that you
85are able to modify your client code.In Go, the modification would look like so:
86
87 config := aws.Config{}
88 config.WithS3ForcePathStyle(true)
89
90S3 path mode works over the network by default for all bucket names.
91
92If you are unable to modify the code, DNS mode can be used, but it comes with further
93restrictions and requires you to be able to modify your local DNS resolution.
94
95If using `localhost` as your endpoint, you will need to add the following to
96`/etc/hosts` for *every bucket you want to fake*:
97
98 127.0.0.1 <bucket-name>.localhost
99
100It is trickier if you want other machines to be able to use your fake S3 server
101as you need to be able to modify their DNS resolution as well.
102
103
104## Exemplary usage
105
106### Lambda Example
107
108```javascript
109var AWS = require('aws-sdk')
110
111var ep = new AWS.Endpoint('http://localhost:9000');
112var s3 = new AWS.S3({endpoint: ep});
113
114exports.handle = function (e, ctx) {
115 s3.createBucket({
116 Bucket: '<bucket-name>',
117 }, function(err, data) {
118 if (err) return console.log(err, err.stack);
119 ctx.succeed(data)
120 });
121}
122```
123
124### Upload Example
125
126```html
127<html>
128 <head>
129 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
130 </head>
131 <body>
132
133 <form action="http://localhost:9000/<bucket-name>/" method="post" enctype="multipart/form-data">
134 Key to upload:
135 <input type="input" name="key" value="user/user1/test/<filename>" /><br />
136 <input type="hidden" name="acl" value="public-read" />
137 <input type="hidden" name="x-amz-meta-uuid" value="14365123651274" />
138 <input type="hidden" name="x-amz-server-side-encryption" value="AES256" />
139 <input type="text" name="X-Amz-Credential" value="AKIAIOSFODNN7EXAMPLE/20151229/us-east-1/s3/aws4_request" />
140 <input type="text" name="X-Amz-Algorithm" value="AWS4-HMAC-SHA256" />
141 <input type="text" name="X-Amz-Date" value="20151229T000000Z" />
142
143 Tags for File:
144 <input type="input" name="x-amz-meta-tag" value="" /><br />
145 <input type="hidden" name="Policy" value='<Base64-encoded policy string>' />
146 <input type="hidden" name="X-Amz-Signature" value="<signature-value>" />
147 File:
148 <input type="file" name="file" /> <br />
149 <!-- The elements after this will be ignored -->
150 <input type="submit" name="submit" value="Upload to Amazon S3" />
151 </form>
152</html>
153```
154
155## Similar notable projects
156
157- https://github.com/minio/minio **not similar but powerfull ;-)**
158- https://github.com/andrewgaul/s3proxy by @andrewgaul
159
160## Contributors
161
162A big thank you to all the [contributors](https://github.com/johannesboyne/gofakes3/graphs/contributors),
163especially [Blake @shabbyrobe](https://github.com/shabbyrobe) who pushed this
164little project to the next level!
165
166**Help wanred**
167
){kind=link}
){kind=link}
