{"id":18347007,"url":"https://github.com/k-tomaszewski/notifications","last_synced_at":"2025-04-09T22:55:05.873Z","repository":{"id":257767347,"uuid":"858789951","full_name":"k-tomaszewski/notifications","owner":"k-tomaszewski","description":"Simple Java library for sending notifications from application to a system operator.","archived":false,"fork":false,"pushed_at":"2024-12-16T15:36:14.000Z","size":54,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-09T22:54:57.962Z","etag":null,"topics":["jakarta-mail","java","java-21","notifications","observability"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/k-tomaszewski.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-17T14:37:19.000Z","updated_at":"2025-04-01T12:57:21.000Z","dependencies_parsed_at":"2024-09-18T16:14:57.083Z","dependency_job_id":"ee6812c0-0abf-4e12-adc1-dac6a30b2db3","html_url":"https://github.com/k-tomaszewski/notifications","commit_stats":null,"previous_names":["k-tomaszewski/notifications"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k-tomaszewski%2Fnotifications","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k-tomaszewski%2Fnotifications/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k-tomaszewski%2Fnotifications/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k-tomaszewski%2Fnotifications/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/k-tomaszewski","download_url":"https://codeload.github.com/k-tomaszewski/notifications/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248125629,"owners_count":21051766,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jakarta-mail","java","java-21","notifications","observability"],"created_at":"2024-11-05T21:12:55.791Z","updated_at":"2025-04-09T22:55:05.846Z","avatar_url":"https://github.com/k-tomaszewski.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Notifications\nSimple Java library for sending human-readable notifications from an application to a system operator,\ndedicated for hobbyists, with use of e-mail messages as transport.\n\n## Features\n1. In-memory queue of notifications to be sent.\n2. Requesting to send a notification is fast as the actual sending is done in a dedicated thread.\n3. Requesting to send a notification is safe as no exceptions are thrown by the operation itself.\nYour business logic will not be ruined by some problem with sending a notification.\n4. Redundancy - you can configure many SMTP servers. If one is not available, another will be used.\n5. Retrying - a notification sending is retried if error that occurred is not fatal.\n6. Spring Boot ready.\n7. Simple - you inject and use just one bean that implements `NotificationService` interface, which has one method: `send`.\n8. Dependencies kept to minimum. Dependencies are already present for a typical Spring Boot based application.\n\n## Motivation\nA hobbyist system is usually lacking a 24/7 dedicated monitoring/operations team like employed for enterprise production systems.\nStill a hobbyist system operator/owner needs a handy way to get informed what is happening with his/her system\nwithout a need to look into system logs (which is time-consuming, so it should be avoided if not required). \nSome kind of notifications delivered to an operator/owner are needed.\n\nNext, such notification solution should require minimal effort and cost to deploy and run.\nE-mail messages are freely available for a long time, as one can create and use a mailbox account without \nany cost. Moreover, e-mail clients are freely available for different devices (PC, mobile phone, tablet) and \ndifferent operating systems. This constitutes an ecosystem for simple and cheap delivery of notifications.\n\nThis library is trying to provide a production grade notifications solution that is based on e-mail\nmessages. Of course, there are Java libraries for sending e-mails, like implementations of Java Mail API or\nhttps://github.com/bbottema/simple-java-mail, but they lack functionality related to resilience like:\n- retrying\n- redundancy\n\nOtherwise, these other solutions provide API too complex for a simple task of sending notifications.\n\nThat is why I've started this project.\n\n## Design decisions\n- Java 21\n- Java Mail\n- SMTP\n- Spring Boot\n\n## Usage\n### Dependency\nAdd dependency to Notifications library (use the latest version):\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003eio.github.k_tomaszewski\u003c/groupId\u003e\n  \u003cartifactId\u003enotifications\u003c/artifactId\u003e\n  \u003cversion\u003e1.2.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\nAs of now the library is published only in GiHub Packages repository, so you need to add additional Maven repository in your `pom.xml` like this:\n```xml\n\u003crepositories\u003e\n    \u003crepository\u003e\n        \u003cid\u003egithub_k-tomaszewski_notifications\u003c/id\u003e\n        \u003curl\u003ehttps://maven.pkg.github.com/k-tomaszewski/notifications\u003c/url\u003e\n    \u003c/repository\u003e\n\u003c/repositories\u003e\n```\nMoreover, it seems that GitHub Packages repository requires authentication even for public\nartifacts, so you need to have a GitHub account and you need to setup your credentials\n(GitHub username and access token) for Maven in the `settings.xml` file. Ref:\n- https://maven.apache.org/guides/mini/guide-multiple-repositories.html\n- https://maven.apache.org/guides/mini/guide-deployment-security-settings.html\n- https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry#authenticating-with-a-personal-access-token\n\nExample:\n```xml\n\u003csettings xmlns=\"http://maven.apache.org/SETTINGS/1.0.0\"\n  xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n  xsi:schemaLocation=\"http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd\"\u003e\n  \u003cservers\u003e\n    \u003cserver\u003e\n      \u003cid\u003egithub_k-tomaszewski_notifications\u003c/id\u003e\n      \u003cusername\u003eMY_GITHUB_USERNAME\u003c/username\u003e\n      \u003cpassword\u003eMY_GITHUB_ACCESS_TOKEN\u003c/password\u003e\n    \u003c/server\u003e\n  \u003c/servers\u003e\n\u003c/settings\u003e\n```\nPlease note that the server ID must be the same as repository ID configured in `pom.xml`.\n\n### Spring Boot properties\nIn your Spring Boot properties file (usually `application.yml`) add configuration for\nNotifications library. They are all under the key \"notifications\". The configuration\nconsists of specifying:\n- Target e-mail address for receiving e-mails with notifications (\"notifications.emailTo\")\n- Set of SMTP accounts used for sending notification e-mails (\"notifications.smtp\"). This set\ncannot be empty and can have any number of items with arbitrary keys (like \"sender1\"). Each account \nis defined by sender e-mail address, Java Mail properties and credentials.\n\nFor now credentials can be provided only by specifying a path (\"credentialsFile\") to a text file containing one or two lines\nof text. If only one line is present this is interpreted as a password and the username is assumed to be the same\nas `emailFrom` property. If two lines of text are present then the first line is username\nand the second line is the password.\n\nExample:\n```yaml\nnotifications:\n  emailTo: target@somemail.com\n  smtp:\n    sender1:\n      emailFrom: sender1@host1.pl\n      properties:\n        mail.smtp.host: smtp.foo.pl\n        mail.smtp.port: 465\n        mail.smtp.ssl.enable: true\n      credentialsFile: /secret/resources/pass.txt\n    sender2:\n      emailFrom: sender2@host2.com\n      properties:\n        mail.smtp.host: smtp-mail.bar.com\n        mail.smtp.port: 587\n        mail.smtp.starttls.required: true\n      credentialsFile: /secret/resources/user_pass.txt\n    default:\n      properties:\n        mail.smtp.auth: true\n        mail.smtp.ssl.protocols: TLSv1.2\n        mail.smtp.connectiontimeout: 1000\n        mail.smtp.timeout: 5000\n```\n\n### Spring Boot bean\nInclude the configuration class for Notifications library, `io.github.k_tomaszewski.notifications.NotificationsConfig`, into your application's Spring Boot configuration. Example:\n```java\n@Configuration\n@Import(NotificationsConfig.class)\npublic class MyConfig {\n  // ...\n}\n```\nThen you can inject a Spring bean implementing `io.github.k_tomaszewski.notifications.NotificationService` interface, which is the one\nyou use for sending notifications.\n\n### Disabling notifications\nIn certain cases, for example tests, it is handy to have notifications disabled. To disable notifications\nyou need to set following Spring Boot property:\n```yaml\nnotifications.enabled: false\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fk-tomaszewski%2Fnotifications","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fk-tomaszewski%2Fnotifications","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fk-tomaszewski%2Fnotifications/lists"}