Ecosyste.ms: Awesome

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

Awesome Lists | Featured Topics | Projects

https://github.com/jgosmann/doveseed

Doveseed is a backend service for email subscriptions to RSS feeds.
https://github.com/jgosmann/doveseed

email-sender rss subscription

Last synced: about 1 month ago
JSON representation

Doveseed is a backend service for email subscriptions to RSS feeds.

Awesome Lists containing this project

README 

        
.. image:: https://github.com/jgosmann/doveseed/actions/workflows/ci.yml/badge.svg

  :target: https://github.com/jgosmann/doveseed/actions/workflows/ci.yml

  :alt: CI and release pipeline

.. image:: https://codecov.io/gh/jgosmann/doveseed/branch/main/graph/badge.svg

  :target: https://codecov.io/gh/jgosmann/doveseed

  :alt: Codecov coverage

.. image:: https://img.shields.io/pypi/v/doveseed

  :target: https://pypi.org/project/doveseed/

  :alt: PyPI

.. image:: https://img.shields.io/pypi/pyversions/doveseed

  :target: https://pypi.org/project/doveseed/

  :alt: PyPI - Python Version

.. image:: https://img.shields.io/pypi/l/doveseed

  :target: https://pypi.org/project/doveseed/

  :alt: PyPI - License



.. image:: https://github.com/jgosmann/doveseed/blob/main/doveseed-logo.png

  :alt: Doveseed logo

  :width: 145



Doveseed

========



Doveseed is a backend service for email subscriptions to RSS feeds.



Setup

-----



Configuration

^^^^^^^^^^^^^



Doveseed requires a configuration file in JSON format. Take a look at

``config.sample.json``. The format is as follows:



* ``db``: JSON file in which Doveseed persists its data.

* ``rss``: URL to the RSS feed for which new notifications are to be send.

* ``smtp``



  * ``host``: SMTP host used to send notification emails.

  * ``port``: SMTP port used to send notification emails (defaul: ``0`` = auto-select).

  * ``user``: SMTP logon user name.

  * ``password``: SMTP logon password.

  * ``ssl_mode``: Activate/deactivate SSL/TLS, valid values ``"no-ssl"``, ``"start-tls"``, ``"tls"`` (default ``"start-tls"``).

  * ``check_hostname``: Whether to verify the hostname when using TLS (default ``true``).



* ``template_vars``: Defines template variables to replace in the email templates.



  * ``display_name``: Name for the website to use in emails.

  * ``host``: Hostname of the website.

  * ``sender``: Email address that is sending the notifications.

  * ``confirm_url_format``: Template for the URL that is used for confirmation

    links. The following values will be replaced in it:



    * ``{host}`` with the specified host,

    * ``{email}`` with the email address to confirm,

    * ``{token}`` with the confirmation token,

    * ``{{`` and ``}}`` with ``{`` and ``}``.



* ``email_templates``: Path to the templates for the emails.

* ``confirm_timeout_minutes``: Timeout in minutes during which a subscription needs to be confirmed.



**Ensure that the configuration files have appropriate permissions, i.e. only

readable by you and Doveseed.**



By default the configuration filename is assumed to be ``config.json``.



Email templates

^^^^^^^^^^^^^^^



Templates for the emails sent out are written in

`Jinja `_.

Look in ``templates/example`` for example email templates.

There is a template for each type of email being sent:



* ``new-post.*``: for notifications about new posts,

* ``subscribe.*``: for requesting confirmation to a new subscription,

* and ``unsubscribe.*``: for requesting confirmation to a cancellation of a subscription.



Each of these templates consists out of three files:



* ``*.subject.txt``: for the subject line of the email,

* ``*.txt``: for the plain text version of the email,

* and ``*.html``: for the HTML version of the email.



REST service

^^^^^^^^^^^^



The REST service runs as a Python `ASGI app

`_. See the FastAPI documentation for

`deployment options `_.



CORS

~~~~



To set appropriate CORS headers use the `FastAPI CORSMiddleware

`_. Activate it by adding the

following lines to the file where you instantiate the app::



    from doveseed.app import app

    from fastapi.middleware.cors import CORSMiddleware



    app.add_middleware(

        CORSMiddleware,

        allow_origins=["http://example.com"],

        allow_methods=["GET", "POST"],

        allow_headers=["Authorization"],

    )



ReCaptcha

~~~~~~~~~



You activate `ReCaptcha (v2) `_ verification of

requests with Doveseed.



First, you need to install the required optional dependencies::



    pip install 'doveseed[recaptcha]'



Then, add the follwing lines to the file where you instantiate the app::



    from doveseed.app import app

    from doveseed.recaptcha import ReCaptchaMiddleware



    app.add_middleware = ReCaptchaMiddleware('^/(un)?subscribe/.*', 'recaptcha.json')



Also, create the ``recaptcha.json`` with the required ReCaptcha configuration:



* ``hostnames``: List of hostnames to accept ReCaptchas from.

* ``secret``: The shared key between your site and reCAPTCHA.



**Ensure that the configuration files have appropriate permissions, i.e. only

readable by you and Doveseed.**



Database cleanup

^^^^^^^^^^^^^^^^



Expired pending subscription can be cleaned from the database with::



    python -m doveseed.cli clean 



Ideally, this command is run once per day as a cron job.



Checking for new posts

^^^^^^^^^^^^^^^^^^^^^^



To check for new post and send notification emails run::



    python -m doveseed.cli notify 



This can either run in a regular interval as a cron job or it can be triggered

in some way after new posts have been published.



**Run this command once to initialize the database before going live because

initially all items in the RSS feed will be considered to be old.** (This

prevents sending a notification email for all already existing items in the

feed.)



REST interface

--------------



Health

^^^^^^



To check the service health:



    GET /health



Returns a 204 (no content) status if the service is up and running.



Subscribe

^^^^^^^^^



To subscribe with an email address::



    POST /subscribe/

    Content-Type: application/json



    { captcha: "ReCaptcha returned from Google API" }



This will return a ``201 NO CONTENT`` and send out the email requesting

confirmation.



Unsubscribe

^^^^^^^^^^^



To unsubscribe an email address::



    POST /unsubscribe/

    Content-Type: application/json



    { captcha: "ReCaptcha returned from Google API" }



This will return a ``201 NO CONTENT`` and send out the email requesting

confirmation if the email is subscribed.



Confirm

^^^^^^^



To confirm a request to subscribe or unsubscribe::



    POST /confirm/

    Content-Type: application/json

    Authorization: Bearer 



This will return a ``201 NO CONTENT`` on success,

and ``401 UNAUTHORIZED`` if the token or email is invalid.