@devtion/backend 0.0.0-004e6ad

package/src/functions/timeout.ts

@@ -0,0 +1,296 @@
+import * as functions from "firebase-functions"
+import admin from "firebase-admin"
+import dotenv from "dotenv"
+import {
+    CeremonyTimeoutType,
+    getParticipantsCollectionPath,
+    ParticipantContributionStep,
+    TimeoutType,
+    ParticipantStatus,
+    getTimeoutsCollectionPath,
+    commonTerms
+} from "@devtion/actions"
+import {
+    getCeremonyCircuits,
+    getCurrentServerTimestampInMillis,
+    getDocumentById,
+    queryOpenedCeremonies
+} from "../lib/utils"
+import { COMMON_ERRORS, logAndThrowError, printLog, SPECIFIC_ERRORS } from "../lib/errors"
+import { LogLevel } from "../types/enums"
+
+dotenv.config()
+
+/**
+ * Check and remove the current contributor if it doesn't complete the contribution on the specified amount of time.
+ * @dev since this cloud function is executed every minute, delay problems may occur. See issue #192 (https://github.com/quadratic-funding/mpc-phase2-suite/issues/192).
+ * @notice the reasons why a contributor may be considered blocking are many.
+ * for example due to network latency, disk availability issues, un/intentional crashes, limited hardware capabilities.
+ * the timeout mechanism (fixed/dynamic) could also influence this decision.
+ * this cloud function should check each circuit and:
+ * A) avoid timeout if there's no current contributor for the circuit.
+ * B) avoid timeout if the current contributor is the first for the circuit
+ * and timeout mechanism type is dynamic (suggestion: coordinator should be the first contributor).
+ * C) check if the current contributor is a potential blocking contributor for the circuit.
+ * D) discriminate between blocking contributor (= when downloading, computing, uploading contribution steps)
+ * or verification (= verifying contribution step) timeout types.
+ * E) execute timeout.
+ * E.1) prepare next contributor (if any).
+ * E.2) update circuit contributors waiting queue removing the current contributor.
+ * E.3) assign timeout to blocking contributor (participant doc update + timeout doc).
+ */
+export const checkAndRemoveBlockingContributor = functions
+    .region("europe-west1")
+    .runWith({
+        memory: "1GB"
+    })
+    .pubsub.schedule("every 1 minutes")
+    .onRun(async () => {
+        // Prepare Firestore DB.
+        const firestore = admin.firestore()
+        // Get current server timestamp in milliseconds.
+        const currentServerTimestamp = getCurrentServerTimestampInMillis()
+
+        // Get opened ceremonies.
+        const ceremonies = await queryOpenedCeremonies()
+
+        // For each ceremony.
+        for (const ceremony of ceremonies) {
+            if (!ceremony.data())
+                // Do not use `logAndThrowError` method to avoid the function to exit before checking every ceremony.
+                printLog(COMMON_ERRORS.CM_INEXISTENT_DOCUMENT_DATA.message, LogLevel.WARN)
+            else {
+                // Get ceremony circuits.
+                const circuits = await getCeremonyCircuits(ceremony.id)
+
+                // Extract ceremony data.
+                const { timeoutType: timeoutMechanismType, penalty } = ceremony.data()!
+
+                for (const circuit of circuits) {
+                    if (!circuit.data())
+                        // Do not use `logAndThrowError` method to avoid the function to exit before checking every ceremony.
+                        printLog(COMMON_ERRORS.CM_INEXISTENT_DOCUMENT_DATA.message, LogLevel.WARN)
+                    else {
+                        // Extract circuit data.
+                        const { waitingQueue, avgTimings, dynamicThreshold, fixedTimeWindow } = circuit.data()
+                        const { contributors, currentContributor, failedContributions, completedContributions } =
+                            waitingQueue
+                        const {
+                            fullContribution: avgFullContribution,
+                            contributionComputation: avgContributionComputation,
+                            verifyCloudFunction: avgVerifyCloudFunction
+                        } = avgTimings
+
+                        // Case (A).
+                        if (!currentContributor)
+                            // Do not use `logAndThrowError` method to avoid the function to exit before checking every ceremony.
+                            printLog(
+                                `No current contributor for circuit ${circuit.id} - ceremony ${ceremony.id}`,
+                                LogLevel.WARN
+                            )
+                        else if (
+                            avgFullContribution === 0 &&
+                            avgContributionComputation === 0 &&
+                            avgVerifyCloudFunction === 0 &&
+                            completedContributions === 0 &&
+                            timeoutMechanismType === CeremonyTimeoutType.DYNAMIC
+                        )
+                            printLog(
+                                `No timeout will be executed for the first contributor to the circuit ${circuit.id} - ceremony ${ceremony.id}`,
+                                LogLevel.WARN
+                            )
+                        else {
+                            // Get current contributor document.
+                            const participant = await getDocumentById(
+                                getParticipantsCollectionPath(ceremony.id),
+                                currentContributor
+                            )
+
+                            if (!participant.data())
+                                // Do not use `logAndThrowError` method to avoid the function to exit before checking every ceremony.
+                                printLog(COMMON_ERRORS.CM_INEXISTENT_DOCUMENT_DATA.message, LogLevel.WARN)
+                            else {
+                                // Extract participant data.
+                                const { contributionStartedAt, verificationStartedAt, contributionStep } =
+                                    participant.data()!
+
+                                // Case (C).
+
+                                // Compute dynamic timeout threshold.
+                                const timeoutDynamicThreshold =
+                                    timeoutMechanismType === CeremonyTimeoutType.DYNAMIC
+                                        ? (avgFullContribution / 100) * Number(dynamicThreshold)
+                                        : 0
+
+                                // Compute the timeout expiration date (in ms).
+                                const timeoutExpirationDateInMsForBlockingContributor =
+                                    timeoutMechanismType === CeremonyTimeoutType.DYNAMIC
+                                        ? Number(contributionStartedAt) +
+                                          Number(avgFullContribution) +
+                                          Number(timeoutDynamicThreshold)
+                                        : Number(contributionStartedAt) + Number(fixedTimeWindow) * 60000 // * 60000 = convert minutes to millis.
+
+                                // Case (D).
+                                const timeoutExpirationDateInMsForVerificationCloudFunction =
+                                    contributionStep === ParticipantContributionStep.VERIFYING &&
+                                    !!verificationStartedAt
+                                        ? Number(verificationStartedAt) + 3540000 // 3540000 = 59 minutes in ms.
+                                        : 0
+
+                                // Assign the timeout type.
+                                let timeoutType: string = ""
+
+                                if (
+                                    timeoutExpirationDateInMsForBlockingContributor < currentServerTimestamp &&
+                                    (contributionStep === ParticipantContributionStep.DOWNLOADING ||
+                                        contributionStep === ParticipantContributionStep.COMPUTING ||
+                                        contributionStep === ParticipantContributionStep.UPLOADING ||
+                                        contributionStep === ParticipantContributionStep.COMPLETED)
+                                )
+                                    timeoutType = TimeoutType.BLOCKING_CONTRIBUTION
+
+                                if (
+                                    timeoutExpirationDateInMsForVerificationCloudFunction > 0 &&
+                                    timeoutExpirationDateInMsForVerificationCloudFunction < currentServerTimestamp &&
+                                    contributionStep === ParticipantContributionStep.VERIFYING
+                                )
+                                    timeoutType = TimeoutType.BLOCKING_CLOUD_FUNCTION
+
+                                printLog(
+                                    `${timeoutType} detected for circuit ${circuit.id} - ceremony ${ceremony.id}`,
+                                    LogLevel.DEBUG
+                                )
+
+                                if (!timeoutType)
+                                    // Do not use `logAndThrowError` method to avoid the function to exit before checking every ceremony.
+                                    printLog(
+                                        `No timeout for circuit ${circuit.id} - ceremony ${ceremony.id}`,
+                                        LogLevel.WARN
+                                    )
+                                else {
+                                    // Case (E).
+                                    let nextCurrentContributorId = ""
+
+                                    // Prepare Firestore batch of txs.
+                                    const batch = firestore.batch()
+
+                                    // Remove current contributor from waiting queue.
+                                    contributors.shift()
+
+                                    // Check if someone else is ready to start the contribution.
+                                    if (contributors.length > 0) {
+                                        // Step (E.1).
+
+                                        // Take the next participant to be current contributor.
+                                        nextCurrentContributorId = contributors.at(0)
+
+                                        // Get the document of the next current contributor.
+                                        const nextCurrentContributor = await getDocumentById(
+                                            getParticipantsCollectionPath(ceremony.id),
+                                            nextCurrentContributorId
+                                        )
+
+                                        // Prepare next current contributor.
+                                        batch.update(nextCurrentContributor.ref, {
+                                            status: ParticipantStatus.READY,
+                                            lastUpdated: getCurrentServerTimestampInMillis()
+                                        })
+                                    }
+
+                                    // Step (E.2).
+                                    // Update accordingly the waiting queue.
+                                    batch.update(circuit.ref, {
+                                        waitingQueue: {
+                                            ...waitingQueue,
+                                            contributors,
+                                            currentContributor: nextCurrentContributorId,
+                                            failedContributions: failedContributions + 1
+                                        },
+                                        lastUpdated: getCurrentServerTimestampInMillis()
+                                    })
+
+                                    // Step (E.3).
+                                    batch.update(participant.ref, {
+                                        status: ParticipantStatus.TIMEDOUT,
+                                        lastUpdated: getCurrentServerTimestampInMillis()
+                                    })
+
+                                    // Compute the timeout duration (penalty) in milliseconds.
+                                    const timeoutPenaltyInMs = Number(penalty) * 60000 // 60000 = amount of ms x minute.
+
+                                    // Prepare an empty doc for timeout (w/ auto-gen uid).
+                                    const timeout = await firestore
+                                        .collection(getTimeoutsCollectionPath(ceremony.id, participant.id))
+                                        .doc()
+                                        .get()
+
+                                    // Prepare tx to store info about the timeout.
+                                    batch.create(timeout.ref, {
+                                        type: timeoutType,
+                                        startDate: currentServerTimestamp,
+                                        endDate: currentServerTimestamp + timeoutPenaltyInMs
+                                    })
+
+                                    // Send atomic update for Firestore.
+                                    await batch.commit()
+
+                                    printLog(
+                                        `The contributor ${participant.id} has been identified as potential blocking contributor. A timeout of type ${timeoutType} has been triggered w/ a penalty of ${timeoutPenaltyInMs} ms`,
+                                        LogLevel.DEBUG
+                                    )
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    })
+
+/**
+ * Resume the contributor circuit contribution from scratch after the timeout expiration.
+ * @dev The participant can resume the contribution if and only if the last timeout in progress was verified as expired (status == EXHUMED).
+ */
+export const resumeContributionAfterTimeoutExpiration = functions
+    .region("europe-west1")
+    .runWith({
+        memory: "1GB"
+    })
+    .https.onCall(async (data: { ceremonyId: string }, context: functions.https.CallableContext): Promise<void> => {
+        if (!context.auth || (!context.auth.token.participant && !context.auth.token.coordinator))
+            logAndThrowError(SPECIFIC_ERRORS.SE_AUTH_NO_CURRENT_AUTH_USER)
+
+        if (!data.ceremonyId) logAndThrowError(COMMON_ERRORS.CM_MISSING_OR_WRONG_INPUT_DATA)
+
+        // Get data.
+        const { ceremonyId } = data
+        const userId = context.auth?.uid
+
+        // Look for the ceremony document.
+        const ceremonyDoc = await getDocumentById(commonTerms.collections.ceremonies.name, ceremonyId)
+        const participantDoc = await getDocumentById(getParticipantsCollectionPath(ceremonyId), userId!)
+
+        // Prepare documents data.
+        const participantData = participantDoc.data()
+
+        if (!ceremonyDoc.data() || !participantData) logAndThrowError(COMMON_ERRORS.CM_INEXISTENT_DOCUMENT_DATA)
+
+        // Extract data.
+        const { contributionProgress, status } = participantData!
+
+        // Check pre-condition for resumable contribution after timeout expiration.
+        if (status === ParticipantStatus.EXHUMED)
+            await participantDoc.ref.update({
+                status: ParticipantStatus.READY,
+                lastUpdated: getCurrentServerTimestampInMillis(),
+                tempContributionData: {}
+            })
+        else logAndThrowError(SPECIFIC_ERRORS.SE_CONTRIBUTE_CANNOT_PROGRESS_TO_NEXT_CIRCUIT)
+
+        printLog(
+            `Contributor ${userId} can retry the contribution for the circuit in position ${
+                contributionProgress + 1
+            } after timeout expiration`,
+            LogLevel.DEBUG
+        )
+    })

package/src/functions/user.ts

@@ -0,0 +1,167 @@
+import * as functions from "firebase-functions"
+import { UserRecord } from "firebase-functions/v1/auth"
+import admin from "firebase-admin"
+import dotenv from "dotenv"
+import { commonTerms, githubReputation } from "@devtion/actions"
+import { encode } from "html-entities"
+import { getGitHubVariables, getCurrentServerTimestampInMillis } from "../lib/utils"
+import { logAndThrowError, makeError, printLog, SPECIFIC_ERRORS } from "../lib/errors"
+import { LogLevel } from "../types/enums"
+
+dotenv.config()
+/**
+ * Record the authenticated user information inside the Firestore DB upon authentication.
+ * @dev the data is recorded in a new document in the `users` collection.
+ * @notice this method is automatically triggered upon user authentication in the Firebase app
+ * which uses the Firebase Authentication service.
+ */
+export const registerAuthUser = functions
+    .region("europe-west1")
+    .runWith({
+        memory: "1GB"
+    })
+    .auth.user()
+    .onCreate(async (user: UserRecord) => {
+        // Get DB.
+        const firestore = admin.firestore()
+        // Get user information.
+        if (!user.uid) logAndThrowError(SPECIFIC_ERRORS.SE_AUTH_NO_CURRENT_AUTH_USER)
+        // The user object has basic properties such as display name, email, etc.
+        const { displayName } = user
+        const { email } = user
+        const { photoURL } = user
+        const { emailVerified } = user
+        // Metadata.
+        const { creationTime } = user.metadata
+        const { lastSignInTime } = user.metadata
+        // The user's ID, unique to the Firebase project. Do NOT use
+        // this value to authenticate with your backend server, if
+        // you have one. Use User.getToken() instead.
+        const { uid } = user
+        // Reference to a document using uid.
+        const userRef = firestore.collection(commonTerms.collections.users.name).doc(uid)
+        // html encode the display name (or put the ID if the name is not displayed)
+        const encodedDisplayName =
+            user.displayName === "Null" || user.displayName === null ? user.uid : encode(displayName)
+
+        // store the avatar URL of a contributor
+        let avatarUrl: string = ""
+        // we only do reputation check if the user is not a coordinator
+        if (
+            !(
+                email?.endsWith(`@${process.env.CUSTOM_CLAIMS_COORDINATOR_EMAIL_ADDRESS_OR_DOMAIN}`) ||
+                email === process.env.CUSTOM_CLAIMS_COORDINATOR_EMAIL_ADDRESS_OR_DOMAIN
+            )
+        ) {
+            const auth = admin.auth()
+            // if provider == github.com let's use our functions to check the user's reputation
+            if (user.providerData.length > 0 && user.providerData[0].providerId === "github.com") {
+                const vars = getGitHubVariables()
+
+                // this return true or false
+                try {
+                    const { reputable, avatarUrl: avatarURL } = await githubReputation(
+                        user.providerData[0].uid,
+                        vars.minimumFollowing,
+                        vars.minimumFollowers,
+                        vars.minimumPublicRepos,
+                        vars.minimumAge
+                    )
+                    if (!reputable) {
+                        // Delete user
+                        await auth.deleteUser(user.uid)
+                        // Throw error
+                        logAndThrowError(
+                            makeError(
+                                "permission-denied",
+                                "The user is not allowed to sign up because their Github reputation is not high enough.",
+                                `The user ${
+                                    user.displayName === "Null" || user.displayName === null
+                                        ? user.uid
+                                        : user.displayName
+                                } is not allowed to sign up because their Github reputation is not high enough. Please contact the administrator if you think this is a mistake.`
+                            )
+                        )
+                    }
+                    // store locally
+                    avatarUrl = avatarURL
+                    printLog(
+                        `Github reputation check passed for user ${
+                            user.displayName === "Null" || user.displayName === null ? user.uid : user.displayName
+                        }`,
+                        LogLevel.DEBUG
+                    )
+                } catch (error: any) {
+                    // Delete user
+                    await auth.deleteUser(user.uid)
+                    logAndThrowError(
+                        makeError(
+                            "permission-denied",
+                            "There was an error while checking the user's Github reputation.",
+                            `${error}`
+                        )
+                    )
+                }
+            }
+        }
+        // Set document (nb. we refer to providerData[0] because we use Github OAuth provider only).
+        // In future releases we might want to loop through the providerData array as we support
+        // more providers.
+        await userRef.set({
+            name: encodedDisplayName,
+            encodedDisplayName,
+            // Metadata.
+            creationTime,
+            lastSignInTime: lastSignInTime || creationTime,
+            // Optional.
+            email: email || "",
+            emailVerified: emailVerified || false,
+            photoURL: photoURL || "",
+            lastUpdated: getCurrentServerTimestampInMillis()
+        })
+
+        // we want to create a new collection for the users to store the avatars
+        const avatarRef = firestore.collection(commonTerms.collections.avatars.name).doc(uid)
+        await avatarRef.set({
+            avatarUrl: avatarUrl || ""
+        })
+        printLog(`Authenticated user document with identifier ${uid} has been correctly stored`, LogLevel.DEBUG)
+        printLog(`Authenticated user avatar with identifier ${uid} has been correctly stored`, LogLevel.DEBUG)
+    })
+/**
+ * Set custom claims for role-based access control on the newly created user.
+ * @notice this method is automatically triggered upon user authentication in the Firebase app
+ * which uses the Firebase Authentication service.
+ */
+export const processSignUpWithCustomClaims = functions
+    .region("europe-west1")
+    .runWith({
+        memory: "1GB"
+    })
+    .auth.user()
+    .onCreate(async (user: UserRecord) => {
+        // Get user information.
+        if (!user.uid) logAndThrowError(SPECIFIC_ERRORS.SE_AUTH_NO_CURRENT_AUTH_USER)
+        // Prepare state.
+        let customClaims: any
+        // Check if user meets role criteria to be a coordinator.
+        if (
+            user.email &&
+            (user.email.endsWith(`@${process.env.CUSTOM_CLAIMS_COORDINATOR_EMAIL_ADDRESS_OR_DOMAIN}`) ||
+                user.email === process.env.CUSTOM_CLAIMS_COORDINATOR_EMAIL_ADDRESS_OR_DOMAIN)
+        ) {
+            customClaims = { coordinator: true }
+            printLog(`Authenticated user ${user.uid} has been identified as coordinator`, LogLevel.DEBUG)
+        } else {
+            customClaims = { participant: true }
+            printLog(`Authenticated user ${user.uid} has been identified as participant`, LogLevel.DEBUG)
+        }
+        try {
+            // Set custom user claims on this newly created user.
+            await admin.auth().setCustomUserClaims(user.uid, customClaims)
+        } catch (error: any) {
+            const specificError = SPECIFIC_ERRORS.SE_AUTH_SET_CUSTOM_USER_CLAIMS_FAIL
+            const additionalDetails = error.toString()
+            logAndThrowError(makeError(specificError.code, specificError.message, additionalDetails))
+        }
+    })