@flink-app/github-app-plugin 0.12.1-alpha.38

package/examples/error-handling.ts

@@ -0,0 +1,396 @@
+/**
+ * Comprehensive Error Handling Example
+ *
+ * This example demonstrates:
+ * - Handling installation errors
+ * - API client error handling
+ * - GitHub API rate limiting
+ * - Permission errors
+ * - Network errors
+ * - Retry logic
+ */
+
+import { FlinkApp, FlinkContext, GetHandler } from "@flink-app/flink";
+import { githubAppPlugin, GitHubAppErrorCodes } from "@flink-app/github-app-plugin";
+
+interface AppContext extends FlinkContext {
+  plugins: {
+    githubApp: any;
+  };
+}
+
+async function start() {
+  const app = new FlinkApp<AppContext>({
+    name: "GitHub App Error Handling Example",
+    port: 3333,
+
+    db: {
+      uri: process.env.MONGODB_URI || "mongodb://localhost:27017/github-app-error-example",
+    },
+
+    plugins: [
+      githubAppPlugin({
+        appId: process.env.GITHUB_APP_ID!,
+        privateKey: process.env.GITHUB_APP_PRIVATE_KEY!,
+        webhookSecret: process.env.GITHUB_WEBHOOK_SECRET!,
+        clientId: process.env.GITHUB_APP_CLIENT_ID!,
+        clientSecret: process.env.GITHUB_APP_CLIENT_SECRET!,
+
+        onInstallationSuccess: async ({ installationId, account }) => {
+          console.log(`Installation successful: ${installationId}`);
+          return {
+            userId: "demo-user",
+            redirectUrl: "/dashboard",
+          };
+        },
+
+        // Handle installation errors
+        onInstallationError: async ({ error, installationId }) => {
+          console.error(`\n=== Installation Error ===`);
+          console.error(`Code: ${error.code}`);
+          console.error(`Message: ${error.message}`);
+
+          // Handle specific error codes
+          switch (error.code) {
+            case GitHubAppErrorCodes.INVALID_STATE:
+              console.error("CSRF state validation failed");
+              console.error("Possible causes:");
+              console.error("- Session expired");
+              console.error("- State parameter tampered with");
+              console.error("- Clock skew between servers");
+              return {
+                redirectUrl: "/error?message=installation-expired",
+              };
+
+            case GitHubAppErrorCodes.SESSION_EXPIRED:
+              console.error("Installation session expired");
+              console.error("User took too long to complete installation");
+              return {
+                redirectUrl: "/error?message=session-expired&retry=true",
+              };
+
+            case GitHubAppErrorCodes.JWT_SIGNING_FAILED:
+              console.error("Failed to sign JWT");
+              console.error("Check private key configuration");
+              return {
+                redirectUrl: "/error?message=configuration-error",
+              };
+
+            case GitHubAppErrorCodes.TOKEN_EXCHANGE_FAILED:
+              console.error("Failed to exchange JWT for installation token");
+              console.error("Possible causes:");
+              console.error("- Invalid GitHub App credentials");
+              console.error("- GitHub API is down");
+              console.error("- Network connectivity issues");
+              return {
+                redirectUrl: "/error?message=github-unavailable",
+              };
+
+            case GitHubAppErrorCodes.INSTALLATION_SUSPENDED:
+              console.error("Installation is suspended");
+              return {
+                redirectUrl: "/error?message=installation-suspended",
+              };
+
+            default:
+              console.error("Unhandled error:", error);
+              return {
+                redirectUrl: "/error?message=unknown-error",
+              };
+          }
+        },
+
+        // Handle webhook errors
+        onWebhookEvent: async ({ event, payload }, ctx) => {
+          try {
+            console.log(`Processing webhook: ${event}`);
+            // Process webhook...
+          } catch (error: any) {
+            console.error(`Webhook processing error:`, error);
+            // Log error but don't throw (to return 200 to GitHub)
+          }
+        },
+      }),
+    ],
+  });
+
+  await app.start();
+
+  console.log(`
+=================================
+Error Handling Example Started
+=================================
+
+This example demonstrates comprehensive error handling.
+
+Try these scenarios:
+1. Invalid private key - Plugin will fail to start
+2. Expired session - Wait 10+ minutes before completing installation
+3. Invalid repository - Try to access non-existent repo
+4. Permission denied - Try to access repo without permission
+5. Rate limit - Make many API calls rapidly
+
+=================================
+  `);
+}
+
+// Handler with comprehensive error handling
+const GetRepositoryWithErrorHandling: GetHandler<any, any, { owner: string; repo: string }> = async ({
+  ctx,
+  params,
+}) => {
+  const userId = "demo-user";
+  const { owner, repo } = params;
+
+  try {
+    // Step 1: Check if installation exists
+    const installation = await ctx.plugins.githubApp.getInstallation(userId);
+
+    if (!installation) {
+      return {
+        status: 404,
+        data: {
+          error: GitHubAppErrorCodes.INSTALLATION_NOT_FOUND,
+          message: "GitHub App is not installed",
+          action: "install",
+          installUrl: `/github-app/install?user_id=${userId}`,
+        },
+      };
+    }
+
+    // Step 2: Check if installation is suspended
+    if (installation.suspendedAt) {
+      return {
+        status: 403,
+        data: {
+          error: GitHubAppErrorCodes.INSTALLATION_SUSPENDED,
+          message: "Your GitHub App installation is suspended",
+          suspendedAt: installation.suspendedAt,
+          suspendedBy: installation.suspendedBy,
+          action: "contact-admin",
+        },
+      };
+    }
+
+    // Step 3: Check repository access
+    const hasAccess = await ctx.plugins.githubApp.hasRepositoryAccess(userId, owner, repo);
+
+    if (!hasAccess) {
+      return {
+        status: 403,
+        data: {
+          error: GitHubAppErrorCodes.REPOSITORY_NOT_ACCESSIBLE,
+          message: `You do not have access to ${owner}/${repo}`,
+          availableRepos: installation.repositories.map((r: any) => r.fullName),
+          action: "grant-access",
+        },
+      };
+    }
+
+    // Step 4: Get API client and fetch repository
+    const client = await ctx.plugins.githubApp.getClient(installation.installationId);
+
+    try {
+      const repository = await client.getRepository(owner, repo);
+
+      return {
+        status: 200,
+        data: {
+          repository: {
+            name: repository.name,
+            fullName: repository.full_name,
+            description: repository.description,
+            url: repository.html_url,
+          },
+        },
+      };
+    } catch (apiError: any) {
+      // Handle GitHub API specific errors
+      return handleGitHubAPIError(apiError, owner, repo);
+    }
+  } catch (error: any) {
+    // Handle unexpected errors
+    console.error("Unexpected error:", error);
+    return {
+      status: 500,
+      data: {
+        error: GitHubAppErrorCodes.SERVER_ERROR,
+        message: "An unexpected error occurred",
+        details: process.env.NODE_ENV === "development" ? error.message : undefined,
+      },
+    };
+  }
+};
+
+export { GetRepositoryWithErrorHandling };
+
+// Helper function to handle GitHub API errors
+function handleGitHubAPIError(error: any, owner: string, repo: string) {
+  const status = error.response?.status;
+  const githubError = error.response?.data;
+
+  switch (status) {
+    case 401:
+      return {
+        status: 401,
+        data: {
+          error: "authentication-failed",
+          message: "GitHub authentication failed",
+          hint: "Token may be expired or invalid",
+          action: "retry",
+        },
+      };
+
+    case 403:
+      // Check if it's a rate limit error
+      if (error.response?.headers?.["x-ratelimit-remaining"] === "0") {
+        const resetTime = parseInt(error.response.headers["x-ratelimit-reset"], 10) * 1000;
+        const waitTime = Math.ceil((resetTime - Date.now()) / 1000 / 60);
+
+        return {
+          status: 429,
+          data: {
+            error: GitHubAppErrorCodes.API_RATE_LIMIT,
+            message: "GitHub API rate limit exceeded",
+            retryAfter: resetTime,
+            waitMinutes: waitTime,
+            action: "wait-and-retry",
+          },
+        };
+      }
+
+      // Permission denied
+      return {
+        status: 403,
+        data: {
+          error: "permission-denied",
+          message: "GitHub App does not have permission to access this resource",
+          hint: "Check GitHub App permissions in settings",
+          action: "update-permissions",
+        },
+      };
+
+    case 404:
+      return {
+        status: 404,
+        data: {
+          error: "repository-not-found",
+          message: `Repository ${owner}/${repo} not found`,
+          possibleCauses: ["Repository doesn't exist", "Repository is private", "Repository was deleted"],
+          action: "verify-repository",
+        },
+      };
+
+    case 422:
+      return {
+        status: 422,
+        data: {
+          error: "validation-failed",
+          message: "GitHub API validation failed",
+          details: githubError?.errors,
+          action: "check-request",
+        },
+      };
+
+    case 502:
+    case 503:
+    case 504:
+      return {
+        status: 503,
+        data: {
+          error: "github-unavailable",
+          message: "GitHub API is temporarily unavailable",
+          statusCode: status,
+          action: "retry-later",
+        },
+      };
+
+    default:
+      return {
+        status: 500,
+        data: {
+          error: GitHubAppErrorCodes.NETWORK_ERROR,
+          message: "Failed to communicate with GitHub API",
+          statusCode: status,
+          githubError: githubError?.message,
+          action: "retry",
+        },
+      };
+  }
+}
+
+// Handler demonstrating retry logic
+const GetRepositoryWithRetry: GetHandler<any, any, { owner: string; repo: string }> = async ({ ctx, params }) => {
+  const userId = "demo-user";
+  const { owner, repo } = params;
+
+  const maxRetries = 3;
+  const retryDelay = 1000; // 1 second
+
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      console.log(`Attempt ${attempt}/${maxRetries}`);
+
+      const installation = await ctx.plugins.githubApp.getInstallation(userId);
+      if (!installation) {
+        return {
+          status: 404,
+          data: { error: "installation-not-found" },
+        };
+      }
+
+      const client = await ctx.plugins.githubApp.getClient(installation.installationId);
+      const repository = await client.getRepository(owner, repo);
+
+      return {
+        status: 200,
+        data: {
+          repository: {
+            name: repository.name,
+            fullName: repository.full_name,
+          },
+          attempts: attempt,
+        },
+      };
+    } catch (error: any) {
+      const isLastAttempt = attempt === maxRetries;
+
+      // Don't retry on client errors (4xx)
+      const status = error.response?.status;
+      if (status && status >= 400 && status < 500) {
+        return handleGitHubAPIError(error, owner, repo);
+      }
+
+      // Retry on server errors (5xx) or network errors
+      if (!isLastAttempt) {
+        console.log(`Attempt ${attempt} failed, retrying in ${retryDelay}ms...`);
+        await new Promise((resolve) => setTimeout(resolve, retryDelay));
+        continue;
+      }
+
+      // Max retries exceeded
+      return {
+        status: 500,
+        data: {
+          error: "max-retries-exceeded",
+          message: "Failed after multiple retry attempts",
+          attempts: maxRetries,
+        },
+      };
+    }
+  }
+
+  // Should never reach here
+  return {
+    status: 500,
+    data: { error: "unexpected-error" },
+  };
+};
+
+export { GetRepositoryWithRetry };
+
+// Start application
+start().catch((error) => {
+  console.error("Failed to start application:", error);
+  process.exit(1);
+});