"""
Web Push Notification Service
This module provides a Flask - based web service for managing and sending web push notifications
to subscribed clients . It implements the Web Push Protocol with VAPID authentication .
Key Features :
- VAPID key management for secure push notifications
- Subscription management ( subscribe / unsubscribe )
- Scheduled daily notifications
- Test notification endpoints
- Support for direct and check - type notifications
Environment Variables :
ADMIN_PASSWORD : Password for admin endpoints ( default : ' admin ' )
PUSH_SERVER_VERSION : Version identifier for the push server
SECONDS_BETWEEN_NOTIFICATIONS : Interval between notification checks ( default : 300 )
SQLALCHEMY_DATABASE_URI : SQLite database path ( format : " sqlite:////path/to/db " )
Technical Details :
- Uses Flask for web framework
- SQLAlchemy for database operations
- pywebpush for Web Push Protocol implementation
- Threading for background notification processing
- Cryptography for VAPID key generation
Security Notes :
- Implements VAPID authentication
- Admin endpoints require basic auth
- Database connections use SQLite with configurable path
- Message size limits enforced
Author : Matthew Raymer
Version : 1.0 .0
"""
import structlog
logger = structlog . get_logger ( )
from cryptography . hazmat . backends import default_backend
from cryptography . hazmat . primitives import serialization
from cryptography . hazmat . primitives . asymmetric import ec
from flask import Flask , request , jsonify , Response
from models import db , VAPIDKey , Settings , Subscription
from pywebpush import webpush , WebPushException
from sqlalchemy import and_
from typing import Dict , Tuple
import base64
import datetime
import json
import os
import threading
import time
import sqlalchemy . exc
import cryptography . exceptions
CONTACT_EMAIL = " mailto:info@timesafari.app "
# On Time Safari, this title bypasses the filters and shows the message directly.
TITLE_DIRECT_NOTIFICATION = ' DIRECT_NOTIFICATION '
# On Time Safari, this title triggers the API check for the user's latest data.
TITLE_DAILY_INDIVIDUAL_CHECK = ' DAILY_CHECK '
PUSH_SERVER_VERSION = os . getenv ( ' PUSH_SERVER_VERSION ' )
SECONDS_BETWEEN_NOTIFICATIONS_STR = os . getenv (
' SECONDS_BETWEEN_NOTIFICATIONS ' , ' 60 ' )
SECONDS_BETWEEN_NOTIFICATIONS = int ( SECONDS_BETWEEN_NOTIFICATIONS_STR )
app = Flask ( __name__ )
class WebPushService ( ) :
"""
Web Push Notification Service Manager
This class manages web push notification services including VAPID key management ,
subscription handling , and notification delivery . It integrates with Flask to provide
HTTP endpoints and maintains a background thread for scheduled notifications .
Key Responsibilities :
- VAPID key management and generation
- Push notification delivery
- Subscription management
- Daily notification scheduling
- Health check endpoints
Attributes :
latest_subscription_run ( str ) : ISO formatted timestamp of last notification run
app ( Flask ) : Flask application instance
daily_notification_thread ( threading . Thread ) : Background thread for notifications
Public Endpoints :
- / web - push / regenerate - vapid ( POST ) : Regenerate VAPID keys ( admin auth required )
- / web - push / ping ( GET ) : Service health check
- / web - push / vapid ( GET ) : Retrieve current VAPID public key
- / web - push / subscribe ( POST ) : Register new push subscription
- / web - push / unsubscribe ( POST ) : Remove push subscription
- / web - push / send - test ( POST ) : Send test notification
Database Models Used :
- VAPIDKey : Stores VAPID key pairs
- Settings : Stores service configuration
- Subscription : Stores push notification subscriptions
Security Features :
- Admin authentication for sensitive endpoints
- VAPID authentication for push messages
- Input validation
- Subscription verification
- Error handling for expired subscriptions
Threading :
Runs a background thread that :
- Checks for pending notifications every SECONDS_BETWEEN_NOTIFICATIONS
- Processes notifications based on configured notification times
- Handles subscription cleanup for expired endpoints
Error Handling :
- Catches and logs push notification failures
- Handles expired subscriptions
- Manages database transaction errors
- Provides detailed error responses
Dependencies :
- Flask for web framework
- SQLAlchemy for database operations
- pywebpush for Web Push Protocol
- cryptography for key generation
Example Usage :
app = Flask ( __name__ )
web_push_service = WebPushService ( app , " production " )
# Service automatically starts background thread and initializes endpoints
Author : Matthew Raymer
Version : 1.0 .0
"""
latest_subscription_run = None
def __init__ ( self , app , config_name : str ) - > None :
"""
Initialize the Web Push Service with Flask app and configuration .
Args :
app ( Flask ) : Flask application instance to attach service endpoints
config_name ( str ) : Configuration profile name ( e . g . , " production " , " development " )
Initializes :
- Database connection
- VAPID keys if not present
- Background notification thread
- Service endpoints
- Configuration settings
Raises :
RuntimeError : If database initialization fails
Exception : If VAPID key generation fails
"""
# Setting the application instance
self . app = app
self . app . add_url_rule ( ' /web-push/regenerate-vapid ' ,
view_func = self . regenerate_vapid , methods = [ ' POST ' ] )
self . app . add_url_rule (
' /web-push/ping ' , view_func = self . ping , methods = [ ' GET ' ] )
# Setting the database URI for the application, with an absolute path
db_uri = os . getenv ( ' SQLALCHEMY_DATABASE_URI ' ,
' sqlite:////app/instance/data/webpush.db ' )
# This relative path works in docker-compose
# This relative path works on a local run if you link to the dir with app.py from "var/app-instance"
db_uri = os . getenv ( ' SQLALCHEMY_DATABASE_URI ' ,
' sqlite:///data/webpush.db ' )
self . app . config [ ' SQLALCHEMY_DATABASE_URI ' ] = db_uri
# Initializing the database with the application
db . init_app ( self . app )
# Creating a context for the application and initializing services
with self . app . app_context ( ) :
self . _initialize ( )
# Creating and starting a thread to send daily notifications
self . daily_notification_thread = threading . Thread (
target = self . _send_daily_notifications )
self . daily_notification_thread . start ( )
def _generate_and_save_vapid_keys ( self ) - > None :
"""
Generate and store new VAPID keys for push notification authentication .
This method handles the complete lifecycle of VAPID key generation :
1. Generates a new ECDSA private key using SECP256R1 curve
2. Derives the corresponding public key
3. Serializes both keys to base64 format
4. Stores the key pair in the database
Technical Details :
- Uses SECP256R1 elliptic curve for key generation
- Public key format : X9 .62 uncompressed point encoding
- Private key format : PKCS #8 DER encoding
- Both keys are base64 encoded for storage
- No encryption is used for private key storage ( consider as enhancement )
Database Impact :
- Creates new record in VAPIDKey table
- Previous keys should be deleted before calling this method
Security Considerations :
- Private key is stored unencrypted
- Key generation uses cryptographically secure random number generator
- Uses standard cryptographic primitives from cryptography library
Raises :
Exception : If key generation , serialization , or database operations fail
Error details are logged before re - raising
Note :
This is an internal method used during initialization and key rotation .
For key rotation , ensure all existing subscriptions are updated or
removed before rotating keys .
"""
try :
# Generating a private key using the elliptic curve SECP256R1
private_key = ec . generate_private_key (
ec . SECP256R1 ( ) , default_backend ( ) )
# Serializing and encoding the public key to base64 format
public_key_bytes = private_key . public_key ( ) . public_bytes (
encoding = serialization . Encoding . X962 ,
format = serialization . PublicFormat . UncompressedPoint
)
public_key_base64 = base64 . b64encode ( public_key_bytes ) . decode ( )
# Serializing and encoding the private key to base64 format
private_key_bytes = private_key . private_bytes (
encoding = serialization . Encoding . DER ,
format = serialization . PrivateFormat . PKCS8 ,
encryption_algorithm = serialization . NoEncryption ( )
)
private_key_base64 = base64 . b64encode ( private_key_bytes ) . decode ( )
# Saving the keys to the database
key = VAPIDKey ( public_key = public_key_base64 ,
private_key = private_key_base64 )
db . session . add ( key )
db . session . commit ( )
except Exception as e :
logger . error ( " error_generating_vapid_keys " , error = str ( e ) )
raise e
def _initialize ( self ) - > None :
"""
Initialize the WebPushService by ensuring VAPID keys exist .
This method is called during service startup to ensure the necessary VAPID
( Voluntary Application Server Identification ) infrastructure is in place .
Workflow :
1. Checks for existing VAPID keys in database
2. If no keys exist , generates and stores new key pair
3. Maintains exactly one active VAPID key pair at all times
Database Operations :
- Reads from VAPIDKey table
- May write to VAPIDKey table if no keys exist
- Uses SQLAlchemy session for transaction management
Dependencies :
- Requires active database connection
- Must be called within Flask application context
- Depends on _generate_and_save_vapid_keys for key generation
Security Considerations :
- Ensures VAPID authentication is always available
- Maintains cryptographic identity of the service
- Critical for secure push notification delivery
Error Handling :
- Database errors are propagated to caller
- Key generation errors are propagated to caller
Note :
This is an internal method called automatically during service initialization .
Manual calls are not typically necessary unless recovering from a failure state .
"""
# Checking if there are any VAPID keys in the database
if not VAPIDKey . query . first ( ) :
# Generating and saving VAPID keys if none are found
self . _generate_and_save_vapid_keys ( )
@staticmethod
def _send_push_notification ( subscription_info : Dict , message : Dict , vapid_private_key : str ) - > Dict [ str , any ] :
"""
Send a web push notification to a subscribed client .
This method handles the delivery of push notifications using the Web Push Protocol ,
including VAPID authentication and error handling .
Args :
subscription_info ( Dict ) : Push subscription information containing :
- endpoint : URL for the push service
- keys : Dict containing :
- p256dh : Client ' s public key
- auth : Client ' s auth secret
message ( Dict ) : Notification payload containing :
- title : Notification title ( required )
- message : Notification body ( optional )
vapid_private_key ( str ) : Base64 - encoded private key for VAPID authentication
Returns :
Dict [ str , any ] : Result containing :
- success ( bool ) : True if notification was sent ( status code 201 )
- message ( str ) : Response text or error message
- result ( Response | bool ) : Response object if successful , False if failed
- unsubscribed ( bool ) : Optional , True if subscription was removed
- error ( Exception ) : Optional , present if an error occurred
Technical Details :
- Uses pywebpush library for Web Push Protocol implementation
- Implements mandatory 1 - second delay after sending
- Automatically handles subscription cleanup for 410 Gone responses
- Uses VAPID for push service authentication
Error Handling :
- Catches and processes WebPushException
- Logs errors with ISO formatted timestamps
- Handles unsubscribe ( 410 Gone ) responses
- Removes invalid subscriptions from database
Database Impact :
- May delete from Subscription table on 410 Gone responses
- Uses SQLAlchemy session for transaction management
Security Considerations :
- Requires valid VAPID authentication
- Handles secure key transmission
- Implements proper subscription cleanup
Note :
The 1 - second delay after sending is a workaround for reliability .
Consider monitoring and adjusting this delay based on service requirements .
"""
try :
result = webpush (
subscription_info = subscription_info ,
data = json . dumps ( message ) ,
vapid_private_key = vapid_private_key ,
vapid_claims = { " sub " : CONTACT_EMAIL }
)
# "because sometimes that's what I had to do to make it work!" - Matthew
time . sleep ( 1 )
return { " success " : result . status_code == 201 , " message " : result . text , " result " : result }
except WebPushException as ex :
now = datetime . datetime . now ( ) . isoformat ( )
endpoint = subscription_info [ ' endpoint ' ]
logger . error ( " push_notification_failed " ,
endpoint = endpoint ,
error = str ( ex ) ,
timestamp = now )
unsubscribed_msg = ' 410 Gone '
unsubscribed = False
if unsubscribed_msg in ex . args [ 0 ] :
subscription = Subscription . query . filter_by (
endpoint = endpoint ) . first ( )
if subscription :
db . session . delete ( subscription )
db . session . commit ( )
logger . info ( " subscription_deleted " ,
endpoint = endpoint ,
reason = " 410_gone " )
unsubscribed = True
else :
logger . warning ( " subscription_not_found " ,
endpoint = endpoint )
else :
logger . error ( " push_notification_error " ,
endpoint = endpoint ,
error = ex . args [ 0 ] )
return { " success " : False , " message " : str ( ex ) , " error " : ex , " unsubscribed " : unsubscribed }
def _send_daily_notifications ( self ) - > None :
"""
Process and send scheduled notifications to all eligible subscribers .
This method runs in a continuous loop as a background thread , processing
notifications based on subscribers ' configured notification times.
Implementation Notes :
The notification time logic stores HH : MM for desired notification times .
While direct time comparison is complex , this approach was chosen for simplicity .
A potential improvement would be to store next notification time per record
and update via SQL calculations , trading more DB updates for clearer logic .
Workflow :
1. Runs in infinite loop with configurable sleep interval
2. For each iteration :
- Checks if notification process is already running
- Determines time window for notifications
- Processes subscriptions within that window
- Updates notification tracking in settings
Time Window Logic :
- If previous notification was before today :
Start : Max ( previous_end_time , yesterday_at_current_time )
End : Beginning of today ( 00 : 00 )
- Otherwise :
Start : Previous notification end time
End : Current time
Database Operations :
- Reads from Settings table for notification tracking
- Updates Settings . running_notify_end_time during processing
- Updates Settings . prev_notify_end_time after completion
- Reads from Subscription table for eligible notifications
- May delete from Subscription table on failed deliveries
Notification Types :
- TITLE_DIRECT_NOTIFICATION : Shows message directly
- TITLE_DAILY_INDIVIDUAL_CHECK : Triggers client API check
Default message provided for DIRECT_NOTIFICATION if none specified
Error Handling :
- Logs all notification failures
- Handles subscription cleanup for failed deliveries
- Maintains notification tracking even on failures
- Prevents concurrent notification processing
Thread Safety :
- Uses Settings . running_notify_end_time as process lock
- Updates notification timestamps atomically
- Handles concurrent access to subscription data
Performance Considerations :
- Processes notifications in batches by time window
- Implements configurable delay between iterations
- Logs performance metrics for monitoring
Dependencies :
- Requires Flask application context
- Needs active database connection
- Uses WebPushService . _send_push_notification for delivery
Configuration :
- Sleep interval : SECONDS_BETWEEN_NOTIFICATIONS environment variable
- Default message : Hardcoded for DIRECT_NOTIFICATION type
Note :
This method runs indefinitely in a background thread .
Termination occurs only when the application shuts down .
"""
while True :
now = datetime . datetime . now ( )
logger . info ( " starting_subscription_check " ,
timestamp = now . isoformat ( ) )
# Creating a context for the application to enable database operations
with self . app . app_context ( ) :
# Retrieve the VAPID key from the database
vapid_key = VAPIDKey . query . first ( )
# Determine the beginning and end time to check for subscriptions
settings = Settings . query . first ( )
if settings . running_notify_end_time is None :
# only do this if we're not already inside one of these loops
# get the previous notify end time from the DB as a datetime
prev_notify_end_time = datetime . datetime . fromisoformat (
settings . prev_notify_end_time )
# if it's before midnight this morning
if prev_notify_end_time < now . replace (
hour = 0 , minute = 0 , second = 0 , microsecond = 0 ) :
# catch us up to the beginning of today
# make the start time the later of: prevNotifyEndTime
# or yesterday at this time
start_time = max (
prev_notify_end_time ,
# if the current time is later in the day, use that
# because the next run will pick up everything from midnight until now today
now . replace ( second = 0 , microsecond = 0 )
- datetime . timedelta ( days = 1 )
)
# make the end time right at midnight at the beginning of today
end_time = now . replace (
hour = 0 , minute = 0 , second = 0 , microsecond = 0 )
start_minute = start_time . strftime ( ' % H: % M ' )
# (we'd never catch anything if we used a non-zero
# start_minute and "00:00" as the end_minute)
end_minute = ' 23:60 ' # gotta catch "23:59", too
else :
# the start time is OK
start_time = prev_notify_end_time
# the end time is now
end_time = now . replace ( second = 0 , microsecond = 0 )
start_minute = start_time . strftime ( ' % H: % M ' )
end_minute = end_time . strftime ( ' % H: % M ' )
# This really should update & continue only if the
# running_notify_end_time is still None,
# just in case another thread started.
settings . running_notify_end_time = end_time . isoformat ( )
# set all subscriptions without a time to the current time
# (these won't be picked-up in the current run, since the
# current minute is the end minute)
Subscription . query . filter_by ( notify_time = None ) . update (
{ Subscription . notify_time : now . strftime ( ' % H: % M ' ) } )
db . session . commit ( )
# this check was generated by Copilot; it's probably unnecessary
if settings . running_notify_end_time == end_time . isoformat ( ) :
# Now get the 'HH:MM' value for start & end so we can
# compare to the notify_time field
# get all the subscriptions that have a notify_time
# between start_minute inclusive and end_minute exclusive
all_subscriptions = Subscription . query . filter (
and_ ( Subscription . notify_time > = start_minute ,
Subscription . notify_time < end_minute )
)
# Send a push notification to each subscribed client
num_subscriptions = all_subscriptions . count ( )
for subscription in all_subscriptions :
subscription_info = {
" endpoint " : subscription . endpoint ,
" keys " : {
" p256dh " : subscription . p256dh ,
" auth " : subscription . auth
}
}
# Construct the push notification message
# The title value is a key, defaulting to trigger
# the device to apply logic and customize both
# title and message.
# See https://gitea.anomalistdesign.com/trent_larson/crowd-funder-for-time-pwa/src/commit/1e6159869fc28ca6e6b5b3d186617d75705100b4/sw_scripts/additional-scripts.js#L65
payload = { " title " : subscription . notify_type }
if subscription . message :
payload [ ' message ' ] = subscription . message
elif subscription . notify_type == TITLE_DIRECT_NOTIFICATION :
# They should get some message.
payload [ ' message ' ] = (
" Just a friendly reminder: click and share some gratitude with the world. " )
result = WebPushService . _send_push_notification (
subscription_info ,
payload ,
vapid_key . private_key )
logger . info ( " subscription_notification_result " ,
subscription_id = subscription . id ,
success = result [ ' success ' ] ,
message = result [ ' message ' ] )
settings . prev_notify_end_time = end_time . isoformat ( )
settings . running_notify_end_time = None
db . session . commit ( )
logger . info ( " notification_batch_complete " ,
count = num_subscriptions ,
timestamp = now . isoformat ( ) )
else :
logger . error ( " failed_to_update_running_notify_end_time " ,
timestamp = now . isoformat ( ) )
else :
logger . info ( " subscription_check_skipped " ,
reason = " already_running " ,
timestamp = now . isoformat ( ) )
self . latest_subscription_run = now . isoformat ( )
# Sleep before repeating
time . sleep ( SECONDS_BETWEEN_NOTIFICATIONS )
# This is an endpoint, routed in __init__
def ping ( self ) - > str :
"""
Endpoint to show liveness info
Returns :
- Response : Text with some subscription - run info
"""
return f " pong ... version { PUSH_SERVER_VERSION } ... with latest subscription run at { self . latest_subscription_run } "
# This is an endpoint, routed in __init__
def regenerate_vapid ( self ) - > Tuple [ Response , int , dict [ str , str ] ] | Tuple [ Response , int ] :
"""
Regenerate VAPID keys for push notification authentication .
This endpoint provides secure rotation of VAPID keys used for push notification
authentication . It requires admin authentication to prevent unauthorized key rotation .
Endpoint Details :
URL : / web - push / regenerate - vapid
Method : POST
Auth Required : Basic Authentication
username : admin
password : ADMIN_PASSWORD environment variable ( default : ' admin ' )
Authentication :
- Uses HTTP Basic Authentication
- Credentials must match configured admin values
- Returns 401 with WWW - Authenticate header on auth failure
Process Flow :
1. Validates admin credentials
2. Deletes existing VAPID keys from database
3. Generates and stores new key pair
4. Returns success / failure response
Database Impact :
- Deletes all records from VAPIDKey table
- Creates new record in VAPIDKey table
- Uses transaction to ensure atomic updates
Security Considerations :
- Requires admin authentication
- Invalidates all existing VAPID keys
- Should be used cautiously as it affects all subscriptions
- Consider notifying subscribers before rotation
Returns :
Union [
Tuple [ Response , int , dict [ str , str ] ] , # Auth failure case
Tuple [ Response , int ] # Success/other failure cases
] :
- Success : ( { " success " : True , " message " : str } , 200 )
- Auth Failure : ( { " error " : str } , 401 , { " WWW-Authenticate " : str } )
- Other Failure : ( { " success " : False , " message " : str } , 500 )
Example Usage :
curl - X POST - H " Authorization: Basic YWRtaW46YWRtaW4= " localhost : 3000 / web - push / regenerate - vapid
Note :
Key rotation may impact existing subscriptions . Consider implementing
a migration strategy for existing subscriptions when rotating keys .
"""
envPassword = os . getenv ( ' ADMIN_PASSWORD ' , ' admin ' )
auth = request . authorization
if ( auth is None
or auth . username is None
or auth . username != ' admin '
or auth . password is None
or auth . password != envPassword ) :
return (
jsonify ( error = ' Wrong password ' ) ,
401 ,
{ ' WWW-Authenticate ' : ' Basic realm= " Login Required " ' }
)
# Creating a context for the application to enable database operations
try :
with self . app . app_context ( ) :
VAPIDKey . query . delete ( )
db . session . commit ( )
self . _generate_and_save_vapid_keys ( )
return jsonify ( success = True , message = " VAPID keys regenerated successfully " ) , 200
except ( sqlalchemy . exc . SQLAlchemyError , cryptography . exceptions . InvalidKey ) as e :
return jsonify ( success = False , message = f ' Error regenerating VAPID keys: { str ( e ) } ' ) , 500
@staticmethod
@app . route ( ' /web-push/vapid ' )
def vapid ( ) - > Response :
"""
Retrieve the current VAPID public key for push notification authentication .
This endpoint provides the public VAPID key needed by web clients to set up
push notification subscriptions . The key is used as part of the Web Push Protocol
to authenticate notification requests .
Endpoint Details :
URL : / web - push / vapid
Method : GET
Auth Required : None
Returns :
Response : JSON object containing :
vapidKey ( str ) : Base64 - encoded VAPID public key
Example Response :
{
" vapidKey " : " BDd3_hVL9fZi9Ybo2UUzA284... "
}
Error Handling :
- Returns 500 if no VAPID key is found in database
- Database errors propagate to global error handler
Security Considerations :
- Public key is safe to expose
- No authentication required as this is public information
- Key rotation handled by separate admin endpoint
Usage Example :
fetch ( ' /web-push/vapid ' )
. then ( response = > response . json ( ) )
. then ( data = > subscribeUserToPush ( data . vapidKey ) ) ;
"""
# Retrieving the VAPID key from the database
key = VAPIDKey . query . first ( )
# Returning the public key in a JSON response
return jsonify ( vapidKey = key . public_key )
@staticmethod
@app . route ( ' /web-push/subscribe ' , methods = [ ' POST ' ] )
def subscribe ( ) - > Tuple [ Response , int ] :
"""
Register a new web push notification subscription .
This endpoint stores subscription details and sends a confirmation notification
to verify the subscription is working correctly .
Endpoint Details :
URL : / web - push / subscribe
Method : POST
Auth Required : None
Request Body :
{
" endpoint " : str , # Push service URL for the subscription
" keys " : {
" p256dh " : str , # Client's public key
" auth " : str # Client's auth secret
} ,
" notifyTime " : {
" utcHour " : int , # Hour in UTC (0-23)
" minute " : int # Optional, defaults to 0 (0-59)
} ,
" notifyType " : str , # Optional, defaults to DAILY_CHECK
# Valid values: DAILY_CHECK, DIRECT_NOTIFICATION
" message " : str # Optional, max 100 chars, used with DIRECT_NOTIFICATION
}
Returns :
Tuple [ Response , int ] : JSON response and HTTP status
Success : ( { " success " : true , " message " : str } , 200 )
Error : ( { " success " : false , " message " : str } , 400 | 500 )
Error Cases :
- 400 : Missing / invalid request parameters
- 400 : Message exceeds 100 characters
- 400 : Invalid notifyType
- 500 : VAPID key not available
Security Considerations :
- Validates all input parameters
- Enforces message length limits
- Stores subscription with creation timestamp
- Associates subscription with current VAPID key
Example Usage :
fetch ( ' /web-push/subscribe ' , {
method : ' POST ' ,
headers : { ' Content-Type ' : ' application/json ' } ,
body : JSON . stringify ( {
endpoint : pushSubscription . endpoint ,
keys : pushSubscription . keys ,
notifyTime : { utcHour : 14 , minute : 30 } ,
notifyType : " DAILY_CHECK "
} )
} ) ;
"""
# Retrieving the content from the incoming request
content = request . json
if ( content is None ) or ( ' endpoint ' not in content ) or ( ' keys ' not in content ) :
return jsonify ( success = False , message = " Missing subscription information " ) , 400
if ( ' p256dh ' not in content [ ' keys ' ] ) or ( ' auth ' not in content [ ' keys ' ] ) :
return jsonify ( success = False , message = " Missing subscription keys information " ) , 400
if ( ' notifyTime ' not in content ) or ( ' utcHour ' not in content [ ' notifyTime ' ] ) :
return jsonify ( success = False , message = " Missing notifyTime information " ) , 400
if ( ' notifyType ' in content ) and ( content [ ' notifyType ' ] not in [ TITLE_DIRECT_NOTIFICATION , TITLE_DAILY_INDIVIDUAL_CHECK ] ) :
return jsonify ( success = False , message = " Invalid notifyType " ) , 400
# Retrieving the VAPID key from the database
vapid_key = VAPIDKey . query . first ( )
# Checking if the VAPID key is available
if not vapid_key :
return jsonify ( success = False , message = " No VAPID keys available " ) , 500
# Constructing the notify_time string
notify_hour = content [ ' notifyTime ' ] [ ' utcHour ' ]
if ' minute ' in content [ ' notifyTime ' ] :
notify_minute = content [ ' notifyTime ' ] [ ' minute ' ]
else :
notify_minute = 0
notify_time = ' {:02d} ' . format (
notify_hour ) + " : " + ' {:02d} ' . format ( notify_minute )
notify_type = TITLE_DAILY_INDIVIDUAL_CHECK
if ' notifyType ' in content :
notify_type = content [ ' notifyType ' ]
# check that the message is 100 characters or less
message = None
if ' message ' in content :
if len ( content [ ' message ' ] ) > 100 :
return jsonify ( success = False , message = " Message is too long. Max 100 characters. " ) , 400
else :
message = content [ ' message ' ]
# Creating a new Subscription instance with the provided data
subscription = Subscription ( auth = content [ ' keys ' ] [ ' auth ' ] ,
created_date = datetime . datetime . now ( ) . isoformat ( ) ,
endpoint = content [ ' endpoint ' ] ,
message = message ,
notify_time = notify_time ,
notify_type = notify_type ,
p256dh = content [ ' keys ' ] [ ' p256dh ' ] ,
vapid_key_id = vapid_key . id )
# Saving the subscription data to the database
db . session . add ( subscription )
db . session . commit ( )
# Constructing the subscription information for the push notification
subscription_info = {
" endpoint " : subscription . endpoint ,
" keys " : {
" p256dh " : subscription . p256dh ,
" auth " : subscription . auth
}
}
# Creating a confirmation message for the push notification
message = { " title " : " Subscription Successful " ,
" message " : " Thank you for subscribing! " }
# Sending the confirmation push notification
result = WebPushService . _send_push_notification (
subscription_info , message , vapid_key . private_key )
# Returning the operation status
return jsonify ( success = result [ " success " ] , message = result [ " message " ] ) , 200
@staticmethod
@app . route ( ' /web-push/unsubscribe ' , methods = [ ' POST ' ] )
def unsubscribe ( ) - > Tuple [ Response , int ] :
"""
Remove a web push notification subscription .
This endpoint removes subscription ( s ) for a given endpoint , optionally filtered
by notification type .
Endpoint Details :
URL : / web - push / unsubscribe
Method : POST
Auth Required : None
Request Body :
{
" endpoint " : str , # Required: Push service URL to unsubscribe
" notifyType " : str # Optional: If provided, only removes subscriptions
# of this type (DAILY_CHECK or DIRECT_NOTIFICATION)
}
Returns :
Tuple [ Response , int ] : JSON response and HTTP status
Success : ( { " success " : true , " message " : str } , 200 )
Error : ( { " success " : false , " message " : str } , 400 )
Error Cases :
- 400 : Missing endpoint parameter
Behavior :
- If notifyType is provided : Removes only subscriptions matching both
endpoint and notifyType
- If notifyType is omitted : Removes all subscriptions for the endpoint
Example Usage :
# Remove specific notification type
fetch ( ' /web-push/unsubscribe ' , {
method : ' POST ' ,
headers : { ' Content-Type ' : ' application/json ' } ,
body : JSON . stringify ( {
endpoint : subscription . endpoint ,
notifyType : " DAILY_CHECK "
} )
} ) ;
# Remove all notifications
fetch ( ' /web-push/unsubscribe ' , {
method : ' POST ' ,
headers : { ' Content-Type ' : ' application/json ' } ,
body : JSON . stringify ( {
endpoint : subscription . endpoint
} )
} ) ;
"""
# Retrieving the endpoint from the incoming request
content = request . json
endpoint = content . get ( ' endpoint ' )
if endpoint is None :
return jsonify ( success = False , message = " Missing endpoint information " ) , 400
# Searching for the subscription in the database using the endpoint
if ' notifyType ' in content :
notify_type = content [ ' notifyType ' ]
logger . info ( " unsubscribe_request " ,
endpoint = endpoint ,
notify_type = notify_type )
db . session . query (
Subscription ) . filter (
and_ ( Subscription . endpoint == endpoint ,
Subscription . notify_type == notify_type )
) . delete ( synchronize_session = False )
db . session . commit ( )
else :
logger . info ( " unsubscribe_request " ,
endpoint = endpoint ,
notify_type = " all " )
db . session . query ( Subscription ) . filter (
Subscription . endpoint == endpoint ) . delete ( synchronize_session = False )
db . session . commit ( )
return jsonify ( success = True , message = " Subscription deleted successfully " ) , 200
@staticmethod
@app . route ( ' /web-push/send-test ' , methods = [ ' POST ' ] )
def send_test ( ) - > Tuple [ Response , int ] :
"""
Send a test push notification to a specific client .
This endpoint verifies push notification functionality by sending a test message
to a specified subscription .
Endpoint Details :
URL : / web - push / send - test
Method : POST
Auth Required : None
Request Body :
{
" endpoint " : str , # Required: Push service URL
" keys " : {
" p256dh " : str , # Required: Client's public key
" auth " : str # Required: Client's auth secret
} ,
" title " : str , # Optional: Custom notification title
# (defaults to "Test Notification")
" message " : str # Optional: Custom notification message
# (defaults to "This is a test notification.")
}
Returns :
Tuple [ Response , int ] : JSON response and HTTP status
Success : ( { " success " : true , " message " : str } , 200 )
Error : ( { " success " : false , " message " : str } , 400 | 404 )
Error Cases :
- 400 : Missing required subscription parameters
- 404 : Subscription not found in database
Example Usage :
fetch ( ' /web-push/send-test ' , {
method : ' POST ' ,
headers : { ' Content-Type ' : ' application/json ' } ,
body : JSON . stringify ( {
endpoint : subscription . endpoint ,
keys : subscription . keys ,
title : " Custom Test " ,
message : " Hello, World! "
} )
} ) ;
Note :
This endpoint is useful for :
- Verifying subscription setup
- Testing notification delivery
- Debugging client - side notification handling
"""
# Retrieving the subscription information from the incoming request
content = request . json
endpoint = content . get ( ' endpoint ' )
p256dh = content . get ( ' keys ' , { } ) . get ( ' p256dh ' )
auth = content . get ( ' keys ' , { } ) . get ( ' auth ' )
if ( endpoint is None ) or ( p256dh is None ) or ( auth is None ) :
return jsonify ( { " success " : False , " message " : " Missing subscription information " } ) , 400
# Looking up the subscription in the database
subscription = Subscription . query . filter_by (
endpoint = endpoint , p256dh = p256dh , auth = auth ) . first ( )
# If the subscription is found, call the _send_push_notification method
if subscription :
subscription_info = {
" endpoint " : endpoint ,
" keys " : {
" p256dh " : p256dh ,
" auth " : auth
}
}
title = " Test Notification "
if " title " in content :
title = content [ ' title ' ]
message = " This is a test notification. "
if " message " in content :
message = content [ ' message ' ]
vapid_key = VAPIDKey . query . filter_by (
id = subscription . vapid_key_id ) . first ( )
result = WebPushService . _send_push_notification (
subscription_info ,
{ " title " : title , " message " : message } ,
vapid_key . private_key
)
logger . info ( " test_notification_sent " ,
success = result [ " success " ] ,
message = result [ " message " ] )
return jsonify ( success = result [ " success " ] , message = result [ " message " ] ) , 200
else :
logger . error ( " test_notification_failed " ,
error = " subscription_not_found " ,
request = content )
return jsonify ( { " success " : False , " message " : " Subscription not found " } ) , 404
web_push_service = WebPushService ( app , " app " )
