Update README.md
This commit is contained in:
Shane Tomlinson
GitHub
Родитель
3e8c9f8283
Коммит
27ebcbe775
300
README.md
300
README.md
|
|
@ -1,299 +1,3 @@
|
||||||
# fxa_email_service
|
# This repository has been migrated to https://github.com/mozilla/fxa/tree/master/packages/fxa-email-service
|
||||||
|
|
||||||
[](https://travis-ci.org/mozilla/fxa-email-service)
|
Please file issues and open pull requests against https://github.com/mozilla/fxa
|
||||||
[](https://circleci.com/gh/mozilla/fxa-email-service)
|
|
||||||
[](https://opensource.org/licenses/MPL-2.0)
|
|
||||||
|
|
||||||
* [What's this?](#whats-this)
|
|
||||||
* [How can I set up a dev environment?](#how-can-i-set-up-a-dev-environment)
|
|
||||||
* [For standalone development](#for-standalone-development)
|
|
||||||
* [As part of the FxA stack](#as-part-of-the-FxA-stack)
|
|
||||||
* [How do I run the tests?](#how-do-i-run-the-tests)
|
|
||||||
* [How can I send an email via SES?](#how-can-i-send-an-email-via-ses)
|
|
||||||
* [How can I send an email via Sendgrid?](#how-can-i-send-an-email-via-sendgrid)
|
|
||||||
* [How do bounce, complaint and delivery notifications work?](#how-do-bounce-complaint-and-delivery-notifications-work)
|
|
||||||
|
|
||||||
## What's this?
|
|
||||||
|
|
||||||
The FxA team had an OKR for Q2 2018
|
|
||||||
about decoupling the auth server from SES
|
|
||||||
and making it possible to send email
|
|
||||||
via different providers.
|
|
||||||
Subsequently,
|
|
||||||
some other teams expressed an interest in
|
|
||||||
depending on a standalone email service too.
|
|
||||||
|
|
||||||
This repo started as our experiment
|
|
||||||
to see what a decoupled email-sending service would look like,
|
|
||||||
written in Rust.
|
|
||||||
It is now handling all FxA email traffic in production,
|
|
||||||
and we are gradually separating it from the FxA stack
|
|
||||||
to run as a standalone service
|
|
||||||
in its own right.
|
|
||||||
|
|
||||||
You can find out more
|
|
||||||
about the structure of the code
|
|
||||||
from the [developer docs](https://mozilla.github.io/fxa-email-service/fxa_email_service/).
|
|
||||||
|
|
||||||
## How can I set up a dev environment?
|
|
||||||
|
|
||||||
### For standalone development
|
|
||||||
|
|
||||||
We're running on the Rust nightly channel,
|
|
||||||
so the easiest way to get set up
|
|
||||||
is with [`rustup`](https://rustup.rs/):
|
|
||||||
|
|
||||||
```
|
|
||||||
curl https://sh.rustup.rs -sSf | sh
|
|
||||||
```
|
|
||||||
|
|
||||||
If you don't want to use nightly as your default channel,
|
|
||||||
you can use it just for this repo instead
|
|
||||||
by installing nightly and then running `rustup override` in this directory:
|
|
||||||
|
|
||||||
```
|
|
||||||
rustup install nightly
|
|
||||||
rustup override set nightly
|
|
||||||
```
|
|
||||||
|
|
||||||
You will also need to install Redis.
|
|
||||||
If your Redis instance
|
|
||||||
is not running on the default port (6379),
|
|
||||||
you will need to set the correct port
|
|
||||||
in `config/local.json`:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"redis": {
|
|
||||||
"port": "..."
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
You can also set `host` in the same way,
|
|
||||||
if your Redis instance is not running locally.
|
|
||||||
|
|
||||||
### As part of the FxA stack
|
|
||||||
|
|
||||||
If you're developing for FxA,
|
|
||||||
the easiest thing to do is
|
|
||||||
set up [`fxa-local-dev`](https://github.com/mozilla/fxa-local-dev).
|
|
||||||
That will install everything you need
|
|
||||||
for running locally,
|
|
||||||
including all of the other FxA services.
|
|
||||||
|
|
||||||
## How do I run the tests?
|
|
||||||
|
|
||||||
A simple `cargo t` will fail
|
|
||||||
because some of the tests are not threadsafe
|
|
||||||
(they rely on setting environment variables
|
|
||||||
that will conflict with other concurrent tests).
|
|
||||||
To run the tests in a single thread instead,
|
|
||||||
a shell script is provided
|
|
||||||
to save you some keystrokes:
|
|
||||||
|
|
||||||
```
|
|
||||||
./t
|
|
||||||
```
|
|
||||||
|
|
||||||
That script assumes you have an instance of [`fxa-auth-db-mysql`](https://github.com/mozilla/fxa-auth-db-mysql)
|
|
||||||
running locally on port 8000,
|
|
||||||
which will be the case if you're running `fxa-local-dev`
|
|
||||||
|
|
||||||
If that's not the case, don't worry.
|
|
||||||
There is another script provided
|
|
||||||
to save you even more keystrokes
|
|
||||||
if you're running standalone:
|
|
||||||
|
|
||||||
```
|
|
||||||
./tdb
|
|
||||||
```
|
|
||||||
|
|
||||||
That script will clone a local copy of the db repo
|
|
||||||
and start it in the background.
|
|
||||||
At the end of the script,
|
|
||||||
the db process will be left running in the background
|
|
||||||
(but subsequent runs of the script
|
|
||||||
won't start extra db processes,
|
|
||||||
you'll only be left with that one).
|
|
||||||
If you want to kill your db process,
|
|
||||||
you can find it with:
|
|
||||||
|
|
||||||
```
|
|
||||||
ps -ef | grep "node bin/server"
|
|
||||||
```
|
|
||||||
|
|
||||||
## How can I send an email via SES?
|
|
||||||
|
|
||||||
You'll need to set up some config
|
|
||||||
with your AWS credentials.
|
|
||||||
That can be with environment variables:
|
|
||||||
|
|
||||||
* `FXA_EMAIL_AWS_KEYS_ACCESS`
|
|
||||||
* `FXA_EMAIL_AWS_KEYS_SECRET`
|
|
||||||
|
|
||||||
Or in `config/local.json`:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"aws": {
|
|
||||||
"keys": {
|
|
||||||
"access": "...",
|
|
||||||
"secret": "..."
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
`config/local.json` is included in `.gitignore`,
|
|
||||||
so you don't have to worry about your keys
|
|
||||||
being accidentally leaked on GitHub.
|
|
||||||
|
|
||||||
Also note that the AWS IAM limits sending
|
|
||||||
to approved `from` addresses.
|
|
||||||
Again, you can set that via environment variables:
|
|
||||||
|
|
||||||
* `FXA_EMAIL_SENDER_ADDRESS`
|
|
||||||
* `FXA_EMAIL_SENDER_NAME`
|
|
||||||
|
|
||||||
Or in `config/local.json`:
|
|
||||||
|
|
||||||
```json
|
|
||||||
"sender": {
|
|
||||||
"address": "verification@latest.dev.lcip.org",
|
|
||||||
"name": "Firefox Accounts"
|
|
||||||
},
|
|
||||||
```
|
|
||||||
|
|
||||||
Once you have config set,
|
|
||||||
you can start the service with:
|
|
||||||
|
|
||||||
```
|
|
||||||
cargo r --bin fxa_email_send
|
|
||||||
```
|
|
||||||
|
|
||||||
Then you can use `curl`
|
|
||||||
to send requests:
|
|
||||||
|
|
||||||
```
|
|
||||||
curl \
|
|
||||||
-d '{"to":"foo@example.com","subject":"bar","body":{"text":"baz"}}' \
|
|
||||||
-H 'Content-Type: application/json' \
|
|
||||||
http://localhost:8001/send
|
|
||||||
```
|
|
||||||
|
|
||||||
If everything is set-up correctly,
|
|
||||||
you should receive email pretty much instantly.
|
|
||||||
|
|
||||||
## How can I send an email via Sendgrid?
|
|
||||||
|
|
||||||
The process is broadly the same as for SES.
|
|
||||||
First set your Sendgrid API key,
|
|
||||||
either using the `FXA_EMAIL_SENGRID_KEY` environment variable
|
|
||||||
or in `config/local.json`:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"sendgrid": {
|
|
||||||
"key": "..."
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Then start the service:
|
|
||||||
|
|
||||||
```
|
|
||||||
cargo r --bin fxa_email_send
|
|
||||||
```
|
|
||||||
|
|
||||||
Or you can use the shortcut:
|
|
||||||
|
|
||||||
```
|
|
||||||
./r
|
|
||||||
```
|
|
||||||
|
|
||||||
Then set `provider` to `sendgrid` in your request payload:
|
|
||||||
|
|
||||||
```
|
|
||||||
curl \
|
|
||||||
-d '{"to":"foo@example.com","subject":"bar","body":{"text":"baz"},"provider":"sendgrid"}' \
|
|
||||||
-H 'Content-Type: application/json' \
|
|
||||||
http://localhost:8001/send
|
|
||||||
```
|
|
||||||
|
|
||||||
If everything is set-up correctly,
|
|
||||||
you should receive email pretty much instantly.
|
|
||||||
|
|
||||||
## How do bounce, complaint and delivery notifications work?
|
|
||||||
|
|
||||||
For consistency with the implementation in the FxA auth server,
|
|
||||||
three separate SQS queues are monitored
|
|
||||||
for bounce, complaint and delivery notifications.
|
|
||||||
Ultimately we expect to simplify this
|
|
||||||
to a single queue for all three notification types.
|
|
||||||
|
|
||||||
Messages on these queues
|
|
||||||
are JSON payloads of the format
|
|
||||||
described in the [AWS docs](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/notification-contents.html)
|
|
||||||
and encoded in [`src/queues/sqs/notification/mod.rs`](src/queues/sqs/notification/mod.rs).
|
|
||||||
|
|
||||||
When a message is received,
|
|
||||||
three things happen in sequence:
|
|
||||||
|
|
||||||
1. For bounce and complaint notification types,
|
|
||||||
a bounce record is created in the auth db.
|
|
||||||
Errors are fatal at this point,
|
|
||||||
steps `2` and `3` will not occur
|
|
||||||
if the db returns an error.
|
|
||||||
|
|
||||||
2. The message is forwarded to the auth server
|
|
||||||
via a fourth, outgoing queue.
|
|
||||||
An error here is not fatal.
|
|
||||||
|
|
||||||
3. The message is deleted from the origin queue.
|
|
||||||
|
|
||||||
Currently, both the incoming and outgoing queues
|
|
||||||
happen to be SQS queues but,
|
|
||||||
since that's an implementation detail,
|
|
||||||
the code separates them
|
|
||||||
behind more abstract `Incoming` and `Outgoing` traits.
|
|
||||||
|
|
||||||
The queue URLs and region
|
|
||||||
are set via config,
|
|
||||||
either using environment variables:
|
|
||||||
|
|
||||||
* `FXA_EMAIL_AWS_REGION`
|
|
||||||
* `FXA_EMAIL_AWS_SQSURLS_BOUNCE`
|
|
||||||
* `FXA_EMAIL_AWS_SQSURLS_COMPLAINT`
|
|
||||||
* `FXA_EMAIL_AWS_SQSURLS_DELIVERY`
|
|
||||||
* `FXA_EMAIL_AWS_SQSURLS_NOTIFICATION`
|
|
||||||
|
|
||||||
Or in `config/local.json`:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"aws": {
|
|
||||||
"region": "...",
|
|
||||||
"sqsurls": {
|
|
||||||
"bounce": "...",
|
|
||||||
"complaint": "...",
|
|
||||||
"delivery": "...",
|
|
||||||
"notification": "..."
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
The queue-handling code runs in a different process
|
|
||||||
to the main email-sending service.
|
|
||||||
You can run it locally like so:
|
|
||||||
|
|
||||||
```
|
|
||||||
cargo r --bin fxa_email_queues
|
|
||||||
```
|
|
||||||
|
|
||||||
There's also a shortcut for this:
|
|
||||||
|
|
||||||
```
|
|
||||||
./rq
|
|
||||||
```
|
|
||||||
|
|
|
||||||
Загрузка…
Ссылка в новой задаче