tech/sxchnge
1
0 Fork 0
Code Issues 6 Pull Requests 1 Actions Packages Projects 1 Releases Wiki Activity

Implement notifications service with shared messaging and email drivers (#36)

Browse Source
This commit is contained in:
Stephan D committed 2026-09-12 14:41:55 +02:00
1 parent 36277b6c45
commit 5c2d36281b
54 files changed
+3746 -6
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

backend/notifications/interface/README.md
+41
View File
@@ -0,0 +1,41 @@
# Notifications service contract
This independent module owns the public internal-service contract. The canonical
source is `proto/v1/interface.proto`; it defines `Send`, `Get`, requests, statuses
and email/SMS/push/Telegram targets. The executable currently implements email.
From the repository root, `make generate-notifications` produces Go/gRPC client
bindings in `notifications/v1`. Generated `.pb.go` files are ignored and must not
be committed. Both backend validation targets generate bindings before compiling.
The generators are pinned in the Makefile; install `protoc` separately.
`make package-notifications-interface` creates a distributable source archive and
a standalone Go client-module archive under `dist/`. Client consumers can generate
bindings for their own language from the source archive. The Go archive contains
the generated bindings and its own go.mod/go.sum, with no executable or shared
infrastructure dependency. Archive generation does not upload to a registry.
Internal Go consumers use the module
`git.sendico.io/tech/sxchnge/notifications/interface` and import
`git.sendico.io/tech/sxchnge/notifications/interface/notifications/v1`. Within this
checkout, use a local replace to this directory and generate before building.
Calls require TLS and `authorization: Bearer <service-token>` metadata. The service
maps tokens to configured caller identities. Callers authorize user/destination
ownership and preferences before sending; this contract is not a public user API.
Parameters are string values keyed by template parameter name. The entire request
is validated before persistence. An identical idempotency key/request returns the
original resource, even after completion or expiry. A changed request conflicts.
Keys are scoped to the authenticated caller and retained at least seven days;
Mongo TTL deletion is asynchronous. Expiry defaults to 24 hours and cannot exceed
24 hours. One email target is accepted; other declared channels return UNIMPLEMENTED.
ACCEPTED means provider acceptance, not delivery or reading. UNKNOWN means the
provider may have sent the message and automatic replay is unsafe. DELIVERED is
reserved for a future receipt implementation. Get never exposes recipient addresses,
rendered content, parameters, provider credentials or raw provider responses.
Keep published template revisions and field numbers stable. Reserve removed
protobuf field/enum names and numbers. Compatible additions belong in v1;
incompatible changes require a new version.
backend/notifications/interface/go.mod
+15
View File
@@ -0,0 +1,15 @@
module git.sendico.io/tech/sxchnge/notifications/interface
go 1.27.0
require (
google.golang.org/grpc v1.83.2
google.golang.org/protobuf v1.36.12
)
require (
golang.org/x/net v0.58.0 // indirect
golang.org/x/sys v0.47.0 // indirect
golang.org/x/text v0.41.0 // indirect
google.golang.org/genproto/googleapis/rpc v0.0.0-20260526163538-3dc84a4a5aaa // indirect
)
backend/notifications/interface/go.sum
+38
View File
@@ -0,0 +1,38 @@
github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
go.opentelemetry.io/otel v1.44.0 h1:JjwHmHpA4iZ3wBxluu2fbbE7j4kqlE8jXyAyPXH7HqU=
go.opentelemetry.io/otel v1.44.0/go.mod h1:BMgjTHL9WPRlRjL2oZCBTL4whCGtXch2H4BhOPIAyYc=
go.opentelemetry.io/otel/metric v1.44.0 h1:1w0gILTcHdr3YI+ixLyjemwrVnsMURbTZFrSYCdDdmc=
go.opentelemetry.io/otel/metric v1.44.0/go.mod h1:8O7hanEPBNgEMmybD3s2VBKcgWOCsA6tzHBPODAiquo=
go.opentelemetry.io/otel/sdk v1.44.0 h1:nHYwb9lK+fJPU/dnT6s7W7Z8itMWyqrnVfbheVYrZ58=
go.opentelemetry.io/otel/sdk v1.44.0/go.mod h1:Osuydd3Se74nqjAKxid74N5eC+jfEqfTegHRnq58oK0=
go.opentelemetry.io/otel/sdk/metric v1.44.0 h1:3LlKgI+VjbVsjNRFZJZAJ30WjXC5VkNRks6si09iEfI=
go.opentelemetry.io/otel/sdk/metric v1.44.0/go.mod h1:5B5pMARnXxKhltooO4xUuCBorl65a4EpnTalObqOigA=
go.opentelemetry.io/otel/trace v1.44.0 h1:jxF5CsGYCe74MCRx2X4g7WsY/VBKRqqpNvXlX/6gtIk=
go.opentelemetry.io/otel/trace v1.44.0/go.mod h1:oLl1jrMQAVo6v3GAggN+1VH9VIz9iUSvW53sW1Q8PIE=
golang.org/x/net v0.58.0 h1:ynWG7rqYi4ccpTEuPZ2QGWHktVEM9DMCj9yzDE0Q7To=
golang.org/x/net v0.58.0/go.mod h1:YwCddHnFlT7eLQqVprV19OnhLGtc5xOKgE0RyqgfWAU=
golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
golang.org/x/text v0.41.0 h1:vz/seA0lnX87Othu2f/0L24RcgrXD9/YFTSuGjj3rH8=
golang.org/x/text v0.41.0/go.mod h1:jvf1O8ajNzZqhSrQBPbutR/EB83Cc0CFrezNQIwbb5M=
gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4=
gonum.org/v1/gonum v0.17.0/go.mod h1:El3tOrEuMpv2UdMrbNlKEh9vd86bmQ6vqIcDwxEOc1E=
google.golang.org/genproto/googleapis/rpc v0.0.0-20260526163538-3dc84a4a5aaa h1:mZHHdPZl0dbGHCflZgAq/Q468DWVFcU2whhB2KAo8fk=
google.golang.org/genproto/googleapis/rpc v0.0.0-20260526163538-3dc84a4a5aaa/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
google.golang.org/grpc v1.83.2 h1:EManeRomTObA0BU7I8vXgg/78uE5MJ9M8B39EX2WscU=
google.golang.org/grpc v1.83.2/go.mod h1:YPI1hK3kDked6iHvgX3tR0y+nX/qpMFKhPgFsokw1S8=
google.golang.org/protobuf v1.36.12 h1:pJOKDDOyeXErUroCihFAd5LQuwXBSpVnKGrj5o/fwxc=
google.golang.org/protobuf v1.36.12/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
backend/notifications/interface/proto/v1/interface.proto
+73
View File
@@ -0,0 +1,73 @@
syntax = "proto3";
package sxchnge.notifications.v1;
option go_package = "git.sendico.io/tech/sxchnge/notifications/interface/notifications/v1;notificationsv1";
import "google/protobuf/timestamp.proto";
// Internal service: authenticate callers over TLS. Send durably queues work.
service NotificationsService {
rpc Send(SendRequest) returns (SendResponse);
rpc Get(GetRequest) returns (GetResponse);
}
message SendRequest {
string idempotency_key = 1; // Required; scoped to authenticated caller, retained seven days.
string user_id = 2; // Caller resolves and authorizes recipient ownership.
string template_id = 3;
string template_version = 4;
map<string, string> parameters = 5;
string locale = 6;
repeated Target targets = 7; // V1 accepts exactly one email target.
google.protobuf.Timestamp expires_at = 8; // Default/max 24h from acceptance.
}
message Target {
oneof destination {
EmailTarget email = 1;
SmsTarget sms = 2;
PushTarget push = 3;
TelegramTarget telegram = 4;
}
}
message EmailTarget { string address = 1; }
message SmsTarget { string phone_number = 1; }
message PushTarget { string endpoint_id = 1; }
message TelegramTarget { string chat_id = 1; }
message SendResponse { Notification notification = 1; }
message GetRequest { string id = 1; }
message GetResponse { Notification notification = 1; }
message Notification {
string id = 1;
string user_id = 2;
string template_id = 3;
string template_version = 4;
repeated Delivery deliveries = 5;
google.protobuf.Timestamp created_at = 6;
google.protobuf.Timestamp updated_at = 7;
google.protobuf.Timestamp expires_at = 8;
}
message Delivery {
string id = 1;
Channel channel = 2;
DeliveryState state = 3;
uint32 attempt_count = 4;
Failure failure = 5;
google.protobuf.Timestamp next_attempt_at = 6;
google.protobuf.Timestamp updated_at = 7;
}
message Failure { string code = 1; string message = 2; }
enum Channel {
CHANNEL_UNSPECIFIED = 0;
CHANNEL_EMAIL = 1;
CHANNEL_SMS = 2;
CHANNEL_PUSH = 3;
CHANNEL_TELEGRAM = 4;
}
enum DeliveryState {
DELIVERY_STATE_UNSPECIFIED = 0;
DELIVERY_STATE_QUEUED = 1;
DELIVERY_STATE_SENDING = 2;
DELIVERY_STATE_RETRY_WAIT = 3;
DELIVERY_STATE_ACCEPTED = 4;
DELIVERY_STATE_DELIVERED = 5; // Reserved for future verified receipts.
DELIVERY_STATE_FAILED = 6;
DELIVERY_STATE_EXPIRED = 7;
DELIVERY_STATE_UNKNOWN = 8; // May have sent; no automatic replay.
}