Some refactor and add docstrings

Author: npalaska

lib/pbench/server/api/resources/db_models.py

@@ -65,6 +65,8 @@ def decode_auth_token(auth_token):
         except jwt.InvalidTokenError:
             return 'Invalid token. Please log in again.'
 
+    # TODO: Add password recovery mechanism
+
 
 class URLModel(db.Model):
     """ User Model for storing user related details """

lib/pbench/server/api/resources/pbench_users.py

@@ -1,6 +1,6 @@
-
+import re
 from flask import request, jsonify, make_response
-from flask_restful import Resource
+from flask_restful import Resource, abort
 from pbench.server.api import app, bcrypt, db, blacklist
 from pbench.server.api.resources.db_models import UserModel
 from flask_jwt_extended import jwt_required
@@ -12,48 +12,107 @@ class RegisterUser(Resource):
     """
 
     def post(self):
+        """
+        Post request for registering a new user.
+        This requires a JSON data with required user metadata fields
+        {
+            "username": "username",
+            "password": "password",
+            "firstName": first_name,
+            "lastName": "last_name",
+            "email": "[email protected]"
+        }
+
+        Required headers include
+
+            Content-Type:   application/json
+            Accept:         application/json
+
+        :return: JSON Payload
+        if we succeed to add a user entry in database, the returned response_object will include the auth_token
+            response_object = {
+                    "status": "success"/"fail",
+                    "status_code": 201/status_code_int,
+                    "message": "Successfully registered."/"failure message",
+                    "auth_token": auth_token.decode(), # Will not present if failed
+                }
+        """
         # get the post data
-        post_data = request.get_json()
+        user_data = request.get_json()
+        if not user_data:
+            app.logger.error("Register User: Invalid json object: %s", request.url)
+            abort(400, message="Register User: Invalid json object in request")
+
+        missing_fields = []
+        if not user_data.get("username"):
+            missing_fields.append("username")
+        if not user_data.get("password"):
+            missing_fields.append("password")
+        if not user_data.get("email"):
+            missing_fields.append("email")
+        if not user_data.get("firstName"):
+            missing_fields.append("firstName")
+        if not user_data.get("lastName"):
+            missing_fields.append("lastName")
+
+        if missing_fields:
+            app.logger.error(
+                f"Register User: missing fields {' '.join(missing_fields)}"
+            )
+            abort(
+                400,
+                message=f"Missing fields to Register User: {' '.join(missing_fields)}",
+            )
+
+        # validate the email field
+        regex = "^[a-z0-9]+[\._]?[a-z0-9]+[@]\w+[.]\w{2,3}$"
+        if not re.search(regex, user_data.get("email")):
+            app.logger.error(f"Register User: invalid email {user_data.get('email')}")
+            abort(400, message=f"Invalid email: {user_data.get('email')}")
+
         # check if user already exist
-        user = UserModel.query.filter_by(username=post_data.get('username')).first()
+        user = UserModel.query.filter_by(username=user_data.get("username")).first()
         if not user:
 
             try:
                 user = UserModel(
-                    username=post_data.get('username'),
-                    password=post_data.get('password'),
-                    firstName=post_data.get('firstName'),
-                    lastName=post_data.get('lastName'),
-                    email=post_data.get('email'),
+                    username=user_data.get("username"),
+                    password=user_data.get("password"),
+                    firstName=user_data.get("firstName"),
+                    lastName=user_data.get("lastName"),
+                    email=user_data.get("email"),
                 )
 
                 # insert the user
                 db.session.add(user)
                 db.session.commit()
-                app.logger.info(f"New user registered, id: {self.id}, username: {self.username}")
+                app.logger.info(
+                    f"New user registered, Name: {user_data.get('firstName')} {user_data.get('lastName')}, "
+                    f"username: {user_data.get('username')}, email: {user_data.get('email')}"
+                )
 
                 # generate the auth token
                 auth_token = user.encode_auth_token(user.id)
                 response_object = {
-                    'status': 'success',
-                    'status_code': 201,
-                    'message': 'Successfully registered.',
-                    'auth_token': auth_token.decode()
+                    "status": "success",
+                    "status_code": 201,
+                    "message": "Successfully registered.",
+                    "auth_token": auth_token.decode(),
                 }
                 return make_response(jsonify(response_object))
 
             except Exception as e:
                 response_object = {
-                    'status': 'fail',
-                    'status_code': 401,
-                    'message': 'Some error occurred. Please try again.'
+                    "status": "fail",
+                    "status_code": 401,
+                    "message": "Some error occurred. Please try again.",
                 }
                 return make_response(jsonify(response_object))
         else:
             response_object = {
-                'status': 'fail',
-                'status_code': 202,
-                'message': 'User already exists. Please Log in.',
+                "status": "fail",
+                "status_code": 202,
+                "message": "User already exists. Please Log in.",
             }
             return make_response(jsonify(response_object))
 
@@ -63,35 +122,59 @@ class LoginAPI(Resource):
     Abstracted pbench API for User Login
     """
     def post(self):
+        """
+        Post request for logging in user.
+        This requires a JSON data with required user metadata fields
+        {
+            "username": "username",
+            "password": "password",
+        }
+
+        Required headers include
+
+            Content-Type:   application/json
+            Accept:         application/json
+
+        :return: JSON Payload
+        if we succeed to decrypt the password hash, the returned response_object will include the auth_token
+            response_object = {
+                    "status": "success"/"fail",
+                    "status_code": 200/status_code_int,
+                    "message": "Successfully logged in."/"failure message",
+                    "auth_token": auth_token.decode(), # Will not present if failed
+                }
+        """
         # get the post data
         post_data = request.get_json()
         try:
             # fetch the user data
-            user = UserModel.query.filter_by(username=post_data.get('username')).first()
+            user = UserModel.query.filter_by(username=post_data.get("username")).first()
 
-            if user and bcrypt.check_password_hash(user.password, post_data.get('password')):
+            if user and bcrypt.check_password_hash(
+                user.password, post_data.get("password")
+            ):
                 auth_token = user.encode_auth_token(user.id)
                 if auth_token:
                     response_object = {
-                        'status': 'success',
-                        'status_code': 200,
-                        'message': 'Successfully logged in.',
-                        'auth_token': auth_token.decode()
+                        "status": "success",
+                        "status_code": 200,
+                        "message": "Successfully logged in.",
+                        "auth_token": auth_token.decode(),
                     }
                     return make_response(jsonify(response_object))
             else:
                 response_object = {
-                    'status': 'fail',
-                    'status_code': 404,
-                    'message': 'User does not exist.'
+                    "status": "fail",
+                    "status_code": 404,
+                    "message": "User does not exist.",
                 }
                 return make_response(jsonify(response_object))
         except Exception as e:
             app.logger.info(f"Exception occurred during user login {e}")
             response_object = {
-                'status': 'fail',
-                'status_code': 500,
-                'message': 'Try again'
+                "status": "fail",
+                "status_code": 500,
+                "message": "Try again",
             }
             return make_response(jsonify(response_object))
 
@@ -102,8 +185,25 @@ class LogoutAPI(Resource):
     """
     @jwt_required
     def post(self):
+        """
+        Post request for logging out a user.
+        This requires a JWT auth token in the header field
+
+        Required headers include
+
+            Content-Type:   application/json
+            Accept:         application/json
+            X-Auth-Token:   JWT token (user received upon login)
+
+        :return: JSON Payload
+            response_object = {
+                    "status": "success"/"fail",
+                    "status_code": 200/status_code_int,
+                    "message": "Successfully logged out."/"failure message",
+                }
+        """
         # get auth token
-        auth_header = request.headers.get('X-Auth-Token')
+        auth_header = request.headers.get("X-Auth-Token")
         if auth_header:
             auth_token = auth_header.split(" ")[1]
 
@@ -112,23 +212,23 @@ def post(self):
                 # Add the token to the blacklist
                 blacklist.add(auth_token)
                 response_object = {
-                    'status': 'success',
-                    'message': 'Successfully logged out.',
-                    'status_code': 200
+                    "status": "success",
+                    "message": "Successfully logged out.",
+                    "status_code": 200,
                 }
                 return make_response(jsonify(response_object))
             else:
                 response_object = {
-                    'status': 'fail',
-                    'message': user_id,
-                    'status_code': 401
+                    "status": "fail",
+                    "message": user_id,
+                    "status_code": 401,
                 }
                 return make_response(jsonify(response_object))
         else:
             response_object = {
-                'status': 'fail',
-                'message': 'Provide a valid auth token.',
-                'status_code': 403
+                "status": "fail",
+                "message": "Provide a valid auth token.",
+                "status_code": 403,
             }
             return make_response(jsonify(response_object))
 
@@ -137,21 +237,43 @@ class GetUser(Resource):
     """
     Abstracted pbench API to get user metadata information
     """
+
     # TODO: We can implement the graphql query to get specific metadata related to a user
     # We dont need to pass user_id to get the user, user id will be retrieved from the jwt encoded auth header
     @jwt_required
     def get(self):
+        """
+        Get request for getting user metadata.
+        This requires a JWT auth token in the header field
+
+        Required headers include
+
+            Content-Type:   application/json
+            Accept:         application/json
+            X-Auth-Token:   JWT token (user received upon login)
+
+        :return: JSON Payload
+            response_object = {
+                    "status": "success"/"fail",
+                    "status_code": 200/status_code_int,
+                    "message": "Successfully registered."/"failure message",
+                    "data": {
+                        "username": username,
+                        "registered_on": registered_on,
+                    }
+                }
+        """
         # get the auth token
-        auth_header = request.headers.get('X-Auth-Token')
-        auth_token = ''
+        auth_header = request.headers.get("X-Auth-Token")
+        auth_token = ""
         if auth_header:
             try:
                 auth_token = auth_header.split(" ")[1]
             except IndexError:
                 response_object = {
-                    'status': 'fail',
-                    'message': 'Bearer token malformed.',
-                    'status_code': 401
+                    "status": "fail",
+                    "message": "Bearer token malformed.",
+                    "status_code": 401,
                 }
                 return make_response(jsonify(response_object))
 
@@ -160,25 +282,20 @@ def get(self):
             if not isinstance(user_id, str):
                 user = UserModel.query.filter_by(id=user_id).first()
                 response_object = {
-                    'status': 'success',
-                    'data': {
-                        'user_id': user.id,
-                        'username': user.username,
-                        'registered_on': user.registered_on
+                    "status": "success",
+                    "data": {
+                        "username": user.username,
+                        "registered_on": user.registered_on,
                     },
-                    'status_code': 200
+                    "status_code": 200,
                 }
                 return make_response(jsonify(response_object))
-            response_object = {
-                'status': 'fail',
-                'message': user_id,
-                'status_code': 403
-            }
+            response_object = {"status": "fail", "message": user_id, "status_code": 403}
             return make_response(jsonify(response_object))
         else:
             response_object = {
-                'status': 'fail',
-                'message': 'Provide a valid auth token.',
-                'status_code': 401
+                "status": "fail",
+                "message": "Provide a valid auth token.",
+                "status_code": 401,
             }
-            return make_response(jsonify(response_object))
+            return make_response(jsonify(response_object))