Database.js Documentation

Database.js Documentation

Database.js is the backbone of the MySQL->MIST interface. Understanding SQL and node.js are imperative to understanding the file, and from there the whole of MIST backend.

General Purpose Database Functions

hashPassword(passwordtohash, callback(hashedPassword))

• Purpose:
  • Hashes a password with blowfish crypt using bcrypt-nodejs.
• Parameters:
  • passwordtohash, a plaintext version of a password to hash
  • callback(hashedPassword, error), a function describing what to do with the result
• Produces:
• hashedPassword, the hashed password
• error, an error if there is one
• Pre-conditions:
• None
• Post-conditions:
• The password will be hashed with Blowfish Crypt
• Preferences:
• This function is not executable from outside database.js.

sanitize(string)

• Purpose:
• Sanitizes a string for MySQL insertion without risking injection using validator.js.
• Parameters:
• string, the string to sanitize
• Produces:
• sanitizedString, a string - returned
• Pre-conditions:
• None
• Post-conditions:
• sanitizedString will be safe to insert into a MySQL
• Preferences:
• This function is not executable outside of this database.js.

query(query, callback(rows, error))

• Purpose:
• Make a query on the current database using mysql-nodejs
• Parameters:
• query, a SQL formatted string
• callback(rows, error), a function describing what to do with the result
• Produces:
• rows, an array of objects which may be accessed with dot syntax using the table's column names.
• error, the error produced by the mysql-nodejs library
• Pre-conditions:
• None
• Post-conditions:
• The MySQL database will be altered as requested
• Preferences:
• SANITIZE YOUR INPUT

User Focused Functions

userExists(checkString, callback(exists))

• Purpose:
• Checks to see if a username or email is already in the database
• Parameters:
• checkstring, a string containing either a username or email address
• callback(exists), a function describing what to do with the result
• Produces:
• exists, a BOOLEAN result
• Pre-conditions:
• None
• Post-conditions:
• None
• Preferences:
  • This function will automatically be called when using the addUser() function, so this is designed to be used while the client is typing on the client side.

addUser(forename, surname, password, email, pgpPublic, username, dob, callback(success, error))

• Purpose:
• Adds a user to the database
• Parameters:
• forename, a string
• surname, a string
• password, a plaintext string (this will be crypted before being sent to the database)
• email, a string
• username, a string
• callback(success, error), a function describing what to do with the result
• Produces:
• success, A BOOLEAN value representing if the insertion was successful
• error, if there was an error, it will be returned here.
• Pre-conditions:
• None
• Post-conditions:
• The database will be appended with the new user, all data will be sanitized, and the password will be hashed.
• Preferences:
• This procedure automatically sanitizes and validates user input, as well as hashes the password. This is the preferred way to interact with the server. However, client-side validation is always a good first-defense.

changeUsername(userid, newUsername, Callback(success, error))

• Purpose:
• To allow a user to change their username
• Parameters:
• userid, the userid of the use who wants to change their password
• newUsername, what they want to change their username to callback
• Produces:
• success, a boolean success indicator
• error, any error occurred along the way
• Pre-conditions:
• None
• Post-conditions:
• Username will to be changed
• Preferences:
• None

changeEmail(userid, newEmail, Callback(success, error))

• Purpose:
• To allow a user to change their emails
• Parameters:
• userid, the userid of the use who wants to change their password
• newEmail, what they want to change their primary email to callback
• Produces:
• success, a boolean success indicator
• error, any error occurred along the way
• Pre-conditions:
• user has logged in, and therefore has access to their userid
• Post-conditions:
• email has been changed
• Preferences:
• None

changeAboutSection(userid, newAbout, Callback(success, error))

• Purpose:
• To allow a user to change their About Section
• Parameters:
• userid, the userid of the use who wants to change their password
• newAbout, a new about section to display
• Produces:
• success, a boolean success indicator
• error, any error occurred along the way
• Pre-conditions:
• user has logged in, and therefore has access to their about section
• Post-conditions:
• about section updates
• Preferences:
• None

logIn(user, password, callback(user, error));

• Purpose:
• To log a user in and get their data from the database
• Parameters:
• user, an email or username
• password, a plaintext password
• Produces:
• user, an object with properties:
  • forename
  • surname
  • hashedPassword
  • email
  • emailVisible
  • pgpPublic
  • username
  • type
  • signupTime
  • lastLoginTime
  • userid
  • about
  • featuredImage
  • token
• error, if one exists
• Pre-conditions:
• None
• Post-conditions:
• The user object will reflect what is in the database
• Preferences:
• Input will be sanitized inside this function

getUser(userid, callback(userObject, error))

• Parameters:
• userid, the id of the user to retrieve
• callback(userObject,error), a function describing what to do with the data
• Produces:
• userObject, an object containing the following properties:
  • forename
  • surname
  • hashedPassword
  • email
  • emailVisible
  • pgpPublic
  • username
  • type
  • signupTime
  • lastLoginTime
  • userid
  • about
  • featuredImage
  • token
• error, if there is one
• Purpose:
• To retrieve information on an user
• Pre-conditions:
• userid corresponds to a user in the database
• Post-conditions:
• All information from the database will be retrieved
• Preferences:
• Use database.getIDforUsername to get the id to pass to this function

getIDforUsername(username, callback(userid, error))

• Parameters:
• username, a string
• callback, a function describing what to do with the data
• Produces:
• userid, the userid associated with the username
• error, if there is one
• Purpose:
• To get the primary key for a username for faster information retrieval in the future
• Pre-conditions:
• None
• Post-conditions:
• The userid will correspond with a user in the database
• Preferences:
• Use in conjunction with database.getUser() to retrieve information on a user

Image Focused Functions

imageExists(userid, checkString)

• Purpose:
• Checks to see if an image with the given string as a title exists for the user
• Parameters:
• userid, the userid of the current session user
• checkstring, a string containing a desired title for an image
• callback(exists), a function describing what to do with the result
• Produces:
• exists, a BOOLEAN result
• Pre-conditions:
• None
• Post-conditions:
• None

toggleLike(userid, imageid, callback(success, error))

• Parameters:
• userid, the user to toggle the like
• imageid, the image to toggle
• Produces:
• success, a boolean
• error, if there is one
• Purpose:
• To make it easy to like or unlike an image, depending on its current status
• Pre-conditions:
• None
• Post-conditions:
• The database will be changed to reflect this change in opinion
• Preferences:
• Automatically sanitizes.

countNumberofLikes(imageid, callback(count, error))

• Parameters:
• imageid, the image to check likes
• Purpose:
• To get the results of ratings in each image
• Pre-conditions:
• Image exists
• Post-conditions:
• Count will be the most up-to-date number of likes
• Preferences:
• Automatically sanitizes.

hasLiked(userid, imageid, callback(liked, error))

• Parameters:
• userid, the user to check likes
• imageid, the image to check likes
• Purpose:
• To check to see if a user has rated an image
• Pre-conditions:
• Image exists
• User exists
• Post-conditions:
• liked will be a boolean
• Preferences:
• Automatically sanitizes.

Workspace Focused Functions

wsExists(userid, checkString, callback(exists))

• Purpose:
• Checks to see if a workspace with the given string as a name exists for the user
• Parameters:
• userid, the userid of the current session user
• checkstring, a string containing a desired name for a workspace
• callback(exists), a function describing what to do with the result
• Produces:
• exists, a BOOLEAN result
• Pre-conditions:
• None
• Post-conditions:
• None

Password Functions

verifyPassword(userid, passwordToTest, callback(verified, error ))

• Purpose:
• Checks to see if a password is correct
• Parameters:
• user, a string that is either the username or the email address
• passwordToTest, a plaintext version of a password to test
• callback(verified, error), a function describing what to do with the result
• Produces:
• verified, A BOOLEAN value representing if the password was correct && the user exists
• Pre-conditions:
• None
• Post-conditions:
• None
• Preferences:
• This procedure automatically sanitizes user input. This will also return false if the user does not exist. The client should never be told if a user exists.

changePassword(userid, oldPassword, newPassword, Callback(success, error))

• Purpose:
• To allow a user to change their password, given they remember their old one.
• Parameters:
• userid, the userid of the use who wants to change their password
• oldPassword, the old password of the user
• newPassword, what they want to change their password to
• callback, a function describing what to do with the response
• Produces:
• success, a boolean success indicator
• error, any error occurred along the way
• Pre-conditions:
• user has logged in, and therefore has access to their userid
• Post-conditions:
• password will be changed if old one is correct
• Preferences:
• None

Search Functions

omnisearch(searchString, callback(resultObject, error))

• Parameters:
• searchString, A string to search
• Purpose:
• Find content in the database similar to a string
• Pre-conditions:
• None
• Post-conditions:
• All results will be returned.
• Preferences:
• None

userSearch(searchString, callback(resultArray, error))

• Parameters:
• searchString, A string to search
• Purpose:
• Find users in the database with a username close to the searchString
• Pre-conditions:
• None
• Post-conditions:
• All results will be returned.
• Preferences:
• Automatically sanitizes.

imageSearch(searchString, callback(resultArray, error))

• Parameters:
• searchString, A string to search
• Purpose:
• Find images in the database with a title similar to searchString
• Pre-conditions:
• None
• Post-conditions:
• All results will be returned.
• Preferences:
• Automatically sanitizes.

commentSearch(searchString, callback(resultArray, error))

• Parameters:
• searchString, A string to search
• Purpose:
• Find comments in the database with content similar to searchString
• Pre-conditions:
• None
• Post-conditions:
• All results will be returned.
• Preferences:
• Automatically sanitizes.

albumSearch(searchString, callback(resultArray, error))

• Parameters:
• searchString, A string to search
• Purpose:
• Find albums in the database with a name similar to searchString
• Pre-conditions:
• None
• Post-conditions:
• All results will be returned.
• Preferences:
• Automatically sanitizes.

functionSearch(searchString, callback(resultArray, error))

• Parameters:
• searchString, A string to search
• Purpose:
• Find functions in the database with a name similar to searchString
• Pre-conditions:
• None
• Post-conditions:
• All results will be returned.
• Preferences:
• Automatically sanitizes.