The free and open Lisp-powered notification nexus
https://codeberg.org/jjba23/pingwing
Do you want to work the complexity away of sending e-mail, Slack or other notifications, from every other program? Specially if you use a (micro)service oriented architecture?
pingwing, a key component of the jointhefreeworld ecosystem, emerges as a robust and extensible solution. Architected in the elegant and powerful dialect of Lisp known as Guile Scheme, this tool gives you power (via REST API and more) to become the central notification system for your platform.
At its core, pingwing exposes a programmatic interface (and more!) allowing you to dispatch messages, electronic mail, and critical alerts with finesse. Forget juggling disparate notification mechanisms; pingwing harmonizes these streams, routing them to your chosen endpoints.
Initial support includes SMTP for email delivery, with a pending integration for Slack (expect webhook wizardry soon!).
The architecture is designed for future expansion, promising connectivity to a diverse range of notification sinks.
This project is powered by Lisp (Guile Scheme), curl , make , SXML and the GNU Artanis web framework, SQLite, among others.
This is free software, licensed under the GNU General Public License 3 or newer.
This tool is compatible with any SMTP provider you can think of, thanks to its simple and agnostic approach.
All you need to do to interact with pingwing is call the /api/v1/tasks with a POST method and give your preferences. See app/api/v1.scm for more details on the API, and lib/pingwing/tasks.scm for more.
curl -v \
-H "Content-Type: application/json" \
-d '{
"task-type": "send-email",
"template": "password-reset",
"template-vars": {
"system-name": "WikiMusic",
"user": "jjbigorra@gmail.com",
"reset-link": "https://gnu.org/"
},
"sender-name": "No Reply - WikiMusic",
"sender-address": "noreply@wikimusic.jointhefreeworld.org",
"subject": "Wikimusic - Password Reset",
"recipients": [
{"name": "Josep Bigorra", "address": "jjbigorra@gmail.com"},
{"name": "Another Person", "address": "jjbigorra+1@gmail.com"}
]
}' \
'http://localhost:50077/api/v1/tasks'
You can submit tasks at super high rates to pingwing since the ingestion and processing are done completely separately. This ensures that we can do a reliable retry mechanism and can handle high volumes of data.
After the task has submitted and picked up by the worker, a message like this will be produced:
MIME-Version: 1.0
Subject: WikiMusic - Password Reset 998c42eb-7472-4e12-aa5a-ffdbe754b430
From: No Reply - WikiMusic <noreply@wikimusic.jointhefreeworld.org>
To: Josep Bigorra <jjbigorra@gmail.com>
Content-Type: multipart/alternative; boundary="pingwing-message-multipart-boundary-33c2b557-7f27-4339-9a85-2385e7ecde9b"
--pingwing-message-multipart-boundary-33c2b557-7f27-4339-9a85-2385e7ecde9b
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
Reset your password:
We have received a request to reset the password for your user account:
User.............
--pingwing-message-multipart-boundary-33c2b557-7f27-4339-9a85-2385e7ecde9b
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
<!DOCTYPE HTML>
<html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8" /><meta http-equiv="X-UA-Compatible" content="IE=edge" />..............
--pingwing-message-multipart-boundary-33c2b557-7f27-4339-9a85-2385e7ecde9b--
Send mail message via SMTP with curl
And the worker will pick it up and send it (programatically for you):
>>= sending mail to email-smtp.eu-west-3.amazonaws.com
curl --verbose --ssl-reqd --url smtp://email-smtp.eu-west-3.amazonaws.com:587 --user "AK*****:*************" --mail-from 'noreply@wikimusic.jointhefreeworld.org' --mail-rcpt 'jjbigorra@gmail.com' --mail-rcpt-allowfails --upload-file tmp/998c42eb-7472-4e12-aa5a-ffdbe754b430-noreply@wikimusic.jointhefreeworld.org-jjbigorra@gmail.com
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0* Host email-smtp.eu-west-3.amazonaws.com:587 was resolved.
IPv6: (none)
IPv4: 15.236.217.177, 15.236.68.209, 15.237.2.166
Trying 15.236.217.177:587...
Connected to email-smtp.eu-west-3.amazonaws.com (15.236.217.177) port 587
< 220 email-smtp.amazonaws.com ESMTP SimpleEmailService-d-I
> EHLO 998c42eb-7472-4e12-aa5a-ffdbe754b430-noreply@wikimusic.jointhefreeworld.org-jjbigorra@gmail.com
< 250-email-smtp.amazonaws.com
< 250-8BITMIME
< 250-STARTTLS
< 250-AUTH PLAIN LOGIN
< 250 Ok
> STARTTLS
< 220 Ready to start TLS
.........................
< 235 Authentication successful.
0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0> MAIL FROM:<noreply@wikimusic.jointhefreeworld.org>
< 250 Ok
> RCPT TO:<jjbigorra@gmail.com>
< 250 Ok
> DATA
< 354 End data with <CR><LF>.<CR><LF>q
} [3028 bytes data]
We are completely uploaded and fine
< 250 Ok 011301968c239ad5-72018cb8-ab51-42dd-8ea6-fd6395124272-000000
100 3028 0 0 100 3028 0 5653 --:--:-- --:--:-- --:--:-- 5649
Connection #0 to host email-smtp.eu-west-3.amazonaws.com left intact`___`
example of how simple a template definition can be:
;;; pingwing -- the free and open Lisp-powered notification nexus
;; Copyright © Josep Bigorra <jjbigorra@gmail.com>
;; pingwing is free software: you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
;; pingwing is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;; You should have received a copy of the GNU General Public License
;; along with pingwing. If not, see <https://www.gnu.org/licenses/>.
(define-module (pingwing templates system-alert)
#:use-module (ice-9 time)
#:use-module (ice-9 format)
#:use-module (ice-9 rdelim)
#:use-module (ice-9 textual-ports)
#:use-module (ice-9 regex)
#:use-module (srfi srfi-1)
#:use-module (srfi srfi-64)
#:use-module (pingwing css)
#:use-module (pingwing html)
#:use-module (ice-9 string-fun)
#:use-module (sxml simple)
#:use-module (ice-9 iconv))
(begin
(define* (system-alert-html-template #:key system-name alert-value)
(let* (
(tree `((html (head ,meta-charset
,meta-ie
,meta-responsive
,meta-color-scheme
,meta-supported-color-schemes
(title ,(gettext "System Alert"))
(style ,mail-style))
(body (h1 (span ,(gettext
"System Alert: "))
(span ,system-name))
(p ,(gettext
"An alert has been triggered from your system"))
(hr (@ (style ,(->style '((margin-top . "1.4em") (margin-bottom . "1.4em"))))))
(p ,alert-value)
,mail-footer)))))
(with-output-to-string (lambda ()
(sxml->xml tree)))))
(export system-alert-html-template))
(begin
(define* (system-alert-plain-template #:key system-name alert-value)
(let* ((content (list (gettext "System Alert")
(gettext
"An alert has been triggered from your system:")
system-name
"----------------------------------"
alert-value
"----------------------------------"
(gettext
"this e-mail was powered by pingwing - the free and open Lisp-powered notification nexus")
"https://codeberg.org/jjba23/pingwing"
(gettext "see pingwing's source code on Codeberg"))))
(string-join content "\n")))
(export system-alert-plain-template))
There are many reasons why a Lisp is a great fit for most software. More specifically, websites are tree like data structures, and you really can't beat Lisps at that, due to homoiconicity and so much more. some thoughts here:
https://jointhefreeworld.org/blog/articles/lisps/why-i-program-in-lisp/index.html