Skip to content

Commit 5b743ab

Browse files
MusilahMusilah
committed
add other services
Signed-off-by: Musilah <nataleigh.nk@gmail.com>
1 parent 0eacc91 commit 5b743ab

File tree

9 files changed

+709
-42
lines changed

9 files changed

+709
-42
lines changed

alarms/README.MD renamed to alarms/README.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
# Alarms
22

3-
The Alarms service stores, manages, and exposes alarms raised by rules and device activity. It consumes alarm events from the message broker, persists them to PostgreSQL, and provides an HTTP API for listing, viewing, updating, and deleting alarms with full authn/authz, metrics, and tracing support.
3+
The Alarms service stores, manages and exposes alarms raised by rules and device activity. It consumes alarm events from the message broker, persists them to PostgreSQL, and provides an HTTP API for listing, viewing, updating, and deleting alarms with full authn/authz, metrics, and tracing support.
44

55
## Configuration
66

7-
The service is configured using the following environment variables (values shown are from `docker/.env` as consumed by `docker/docker-compose.yaml`):
7+
The service is configured using the following environment variables (values shown are from [docker/.env](https://github.com/absmach/magistrala/blob/main/docker/.env) as consumed by [docker/docker-compose.yaml](https://github.com/absmach/magistrala/blob/main/docker/docker-compose.yaml)):
88

99
| Variable | Description | Default |
1010
| --- | --- | --- |
@@ -121,7 +121,7 @@ SMQ_DOMAINS_GRPC_TIMEOUT=300s \
121121

122122
### Docker Compose
123123

124-
The service is available as a Docker container. Refer to `docker/docker-compose.yaml` for the `alarms` and `alarms-db` services and their environment variables. For a full local stack, make sure the auth, domains, and message broker services are also running.
124+
The service is available as a Docker container. Refer to [docker/docker-compose.yaml](https://github.com/absmach/magistrala/blob/main/docker/docker-compose.yaml) for the `alarms` and `alarms-db` services and their environment variables. For a full local stack, make sure the auth, domains, and message broker services are also running.
125125

126126
```bash
127127
docker compose -f docker/docker-compose.yaml up alarms alarms-db

‎consumers/notifiers/README.md‎

Lines changed: 173 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,182 @@
1-
# Notifiers service
1+
# Notifiers
22

3-
Notifiers service provides a service for sending notifications using Notifiers.
4-
Notifiers service can be configured to use different types of Notifiers to send
5-
different types of notifications such as SMS messages, emails, or push notifications.
6-
Service is extensible so that new implementations of Notifiers can be easily added.
7-
Notifiers **are not standalone services** but rather dependencies used by Notifiers service
8-
for sending notifications over specific protocols.
3+
The Notifiers service manages notification subscriptions and dispatches alerts for incoming messages. It stores subscription records (topic + contact), exposes an HTTP API for CRUD operations, and consumes SuperMQ messages to fan out notifications via notifier implementations (SMTP for email, SMPP for SMS). Notifiers are dependencies used by the service, not standalone services.
94

105
## Configuration
116

12-
The service is configured using the environment variables.
13-
The environment variables needed for service configuration depend on the underlying Notifier.
14-
An example of the service configuration for SMTP Notifier can be found [in SMTP Notifier documentation](smtp/README.md).
15-
Note that any unset variables will be replaced with their
16-
default values.
7+
The service is configured using environment variables. Values shown are from [docker/.env](https://github.com/absmach/magistrala/blob/main/docker/.env) when available; otherwise defaults come from code or notifier-specific docs.
178

9+
### SMTP notifier (email)
10+
11+
Used by `consumers/notifiers/smtp` via `internal/email`.
12+
13+
| Variable | Description | Default |
14+
| --- | --- | --- |
15+
| `MG_EMAIL_HOST` | SMTP host | `smtp.mailtrap.io` |
16+
| `MG_EMAIL_PORT` | SMTP port | `2525` |
17+
| `MG_EMAIL_USERNAME` | SMTP username | `18bf7f70705139` |
18+
| `MG_EMAIL_PASSWORD` | SMTP password | `2b0d302e775b1e` |
19+
| `MG_EMAIL_FROM_ADDRESS` | Default from address (used if `from` is empty) | `from@example.com` |
20+
| `MG_EMAIL_FROM_NAME` | Default from name | `Example` |
21+
| `MG_EMAIL_TEMPLATE` | Email template path | `email.tmpl` |
22+
23+
### SMPP notifier (SMS)
24+
25+
#### SMPP transport settings
26+
27+
Defined in `consumers/notifiers/smpp/config.go`.
28+
29+
| Variable | Description | Default |
30+
| --- | --- | --- |
31+
| `MG_SMPP_ADDRESS` | SMPP address in `host:port` format | "" |
32+
| `MG_SMPP_USERNAME` | SMPP username | "" |
33+
| `MG_SMPP_PASSWORD` | SMPP password | "" |
34+
| `MG_SMPP_SYSTEM_TYPE` | SMPP system type | "" |
35+
| `MG_SMPP_SRC_ADDR_TON` | SMPP source address TON | `0` |
36+
| `MG_SMPP_DST_ADDR_TON` | SMPP source address NPI | `0` |
37+
| `MG_SMPP_SRC_ADDR_NPI` | SMPP destination address TON | `0` |
38+
| `MG_SMPP_DST_ADDR_NPI` | SMPP destination address NPI | `0` |
39+
40+
Note: The SMPP env tags are mapped exactly as defined in `consumers/notifiers/smpp/config.go`.
41+
42+
#### SMPP notifier service settings
43+
44+
Defined in `consumers/notifiers/smpp/README.md`.
45+
46+
| Variable | Description | Default |
47+
| --- | --- | --- |
48+
| `MG_SMPP_NOTIFIER_LOG_LEVEL` | Log level for SMPP notifier | `info` |
49+
| `MG_SMPP_NOTIFIER_FROM_ADDRESS` | From address for SMS notifications | "" |
50+
| `MG_SMPP_NOTIFIER_CONFIG_PATH` | Config file path for message broker subjects and payload type | `/config.toml` |
51+
| `MG_SMPP_NOTIFIER_HTTP_HOST` | Service HTTP host | `localhost` |
52+
| `MG_SMPP_NOTIFIER_HTTP_PORT` | Service HTTP port | `9014` |
53+
| `MG_SMPP_NOTIFIER_HTTP_SERVER_CERT` | Service HTTP server certificate path | "" |
54+
| `MG_SMPP_NOTIFIER_HTTP_SERVER_KEY` | Service HTTP server key path | "" |
55+
| `MG_SMPP_NOTIFIER_DB_HOST` | Database host address | `localhost` |
56+
| `MG_SMPP_NOTIFIER_DB_PORT` | Database host port | `5432` |
57+
| `MG_SMPP_NOTIFIER_DB_USER` | Database user | `magistrala` |
58+
| `MG_SMPP_NOTIFIER_DB_PASS` | Database password | `magistrala` |
59+
| `MG_SMPP_NOTIFIER_DB_NAME` | Database name | `subscriptions` |
60+
| `MG_SMPP_NOTIFIER_DB_SSL_MODE` | DB SSL mode (disable, require, verify-ca, verify-full) | `disable` |
61+
| `MG_SMPP_NOTIFIER_DB_SSL_CERT` | DB SSL client cert path | "" |
62+
| `MG_SMPP_NOTIFIER_DB_SSL_KEY` | DB SSL client key path | "" |
63+
| `MG_SMPP_NOTIFIER_DB_SSL_ROOT_CERT` | DB SSL root cert path | "" |
64+
| `SMQ_AUTH_GRPC_URL` | Auth gRPC URL | `localhost:7001` |
65+
| `SMQ_AUTH_GRPC_TIMEOUT` | Auth gRPC timeout | `1s` |
66+
| `MG_AUTH_GRPC_CLIENT_TLS` | Auth client TLS flag | `false` |
67+
| `MG_AUTH_GRPC_CA_CERT` | Auth client CA certs path | "" |
68+
| `SMQ_MESSAGE_BROKER_URL` | Message broker URL | `nats://127.0.0.1:4222` |
69+
| `SMQ_JAEGER_URL` | Jaeger tracing URL | `http://jaeger:14268/api/traces` |
70+
| `SMQ_SEND_TELEMETRY` | Send telemetry to Magistrala call-home server | `true` |
71+
| `MG_SMPP_NOTIFIER_INSTANCE_ID` | SMPP notifier instance ID | "" |
72+
73+
## Features
74+
75+
- **Subscription management**: Create, view, list, and remove notification subscriptions.
76+
- **Topic-based dispatch**: Matches subscriptions by topic and fan-outs to contacts.
77+
- **Multiple notifier backends**: SMTP (email) and SMPP (SMS) implementations are available.
78+
- **Observability**: Exposes `/metrics` and `/health` endpoints.
79+
- **Uniqueness guardrails**: Prevents duplicate subscriptions for the same topic/contact pair.
80+
81+
## Architecture
82+
83+
### Runtime flow
84+
85+
1. Clients register subscriptions through the HTTP API (`topic` + `contact`).
86+
2. The service authenticates the token, assigns an owner ID, and persists the subscription.
87+
3. When a message arrives, the service builds the topic as `channel` or `channel.subtopic`, retrieves matching subscriptions, and gathers contacts.
88+
4. The notifier implementation sends notifications using the configured backend.
89+
90+
### Components
91+
92+
- **HTTP API**: `consumers/notifiers/api` exposes `/subscriptions`, `/health`, and `/metrics`.
93+
- **Service layer**: `consumers/notifiers/service.go` handles authn, ID creation, and notification dispatch.
94+
- **Repository**: `consumers/notifiers/postgres` persists subscriptions and supports filtering.
95+
- **Notifier implementations**: `consumers/notifiers/smtp` (email) and `consumers/notifiers/smpp` (SMS).
96+
- **Email agent**: `internal/email` manages SMTP connectivity and template rendering.
97+
98+
### Subscriptions table
99+
100+
Defined in `consumers/notifiers/postgres/init.go`:
101+
102+
| Column | Type | Description |
103+
| --- | --- | --- |
104+
| `id` | `VARCHAR(254)` | Subscription identifier (primary key) |
105+
| `owner_id` | `VARCHAR(254)` | Owner ID derived from the auth token |
106+
| `contact` | `VARCHAR(254)` | Notification contact (email or phone) |
107+
| `topic` | `TEXT` | Topic to match (`channel` or `channel.subtopic`) |
108+
109+
Constraint: `UNIQUE(topic, contact)`
110+
111+
## Deployment
112+
113+
The Notifiers service is provided as a consumer package. It is typically wired into a notifier-specific binary that provides the HTTP server and message broker subscription. For the SMPP notifier runtime configuration, see `consumers/notifiers/smpp/README.md`.
114+
115+
### Health check
116+
117+
```bash
118+
curl -X GET http://localhost:9014/health \
119+
-H "accept: application/health+json"
120+
```
121+
122+
## Testing
123+
124+
```bash
125+
go test ./consumers/notifiers/...
126+
```
18127

19128
## Usage
20129

21-
Subscriptions service will start consuming messages and sending notifications when a message is received.
130+
The Notifiers service supports the following operations (see `apidocs/openapi/notifiers.yaml`):
131+
132+
| Operation | Method & Path | Description |
133+
| --- | --- | --- |
134+
| `createSubscription` | `POST /subscriptions` | Create a new subscription |
135+
| `listSubscriptions` | `GET /subscriptions` | List subscriptions with filters |
136+
| `viewSubscription` | `GET /subscriptions/{id}` | Retrieve a subscription |
137+
| `removeSubscription` | `DELETE /subscriptions/{id}` | Delete a subscription |
138+
| `health` | `GET /health` | Service health check |
139+
140+
### Example: Create a subscription
141+
142+
```bash
143+
curl -X POST http://localhost:9014/subscriptions \
144+
-H "Authorization: Bearer <your_access_token>" \
145+
-H "Content-Type: application/json" \
146+
-d '{
147+
"topic": "channel.subtopic",
148+
"contact": "user@example.com"
149+
}'
150+
```
151+
152+
### Example: List subscriptions
153+
154+
```bash
155+
curl -X GET "http://localhost:9014/subscriptions?topic=channel.subtopic&contact=user@example.com&limit=20&offset=0" \
156+
-H "Authorization: Bearer <your_access_token>"
157+
```
158+
159+
### Example: View a subscription
160+
161+
```bash
162+
curl -X GET http://localhost:9014/subscriptions/<subscriptionID> \
163+
-H "Authorization: Bearer <your_access_token>"
164+
```
165+
166+
### Example: Remove a subscription
167+
168+
```bash
169+
curl -X DELETE http://localhost:9014/subscriptions/<subscriptionID> \
170+
-H "Authorization: Bearer <your_access_token>"
171+
```
172+
173+
### Example: Health check
174+
175+
```bash
176+
curl -X GET http://localhost:9014/health \
177+
-H "accept: application/health+json"
178+
```
179+
180+
For an in-depth explanation of the Notifiers, see the [official documentation][doc].
22181

23-
[doc]: https://docs.supermq.absmach.eu
182+
[doc]: https://docs.magistrala.absmach.eu/dev-guide/consumers/#notifiers

0 commit comments

Comments
 (0)