Cloud Functions: Mastering Function-as-a-Service

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80

// Optimized Google Cloud Function (TypeScript)
// Global scope runs once per instance - perfect for initialization
 
import { Firestore } from '@google-cloud/firestore';
import { SecretManagerServiceClient } from '@google-cloud/secret-manager';
import { CloudFunctionsContext } from '@google-cloud/functions-framework';
 
// Initialize clients in global scope - reused across invocations
const firestore = new Firestore();
const secretManager = new SecretManagerServiceClient();
 
// Cache secrets to avoid repeated Secret Manager calls
interface CachedSecrets {
  apiKey: string;
  databaseUrl: string;
  expiresAt: number;
}
 
let cachedSecrets: CachedSecrets | null = null;
 
async function getSecrets(): Promise<CachedSecrets> {
  // Return cached secrets if still valid (1 hour TTL)
  if (cachedSecrets && Date.now() < cachedSecrets.expiresAt) {
    return cachedSecrets;
  }
  
  const [apiKeyVersion] = await secretManager.accessSecretVersion({
    name: 'projects/my-project/secrets/api-key/versions/latest'
  });
  
  const [dbUrlVersion] = await secretManager.accessSecretVersion({
    name: 'projects/my-project/secrets/database-url/versions/latest'
  });
  
  cachedSecrets = {
    apiKey: apiKeyVersion.payload?.data?.toString() || '',
    databaseUrl: dbUrlVersion.payload?.data?.toString() || '',
    expiresAt: Date.now() + 3600000  // 1 hour
  };
  
  return cachedSecrets;
}
 
// Lazy initialization pattern for expensive resources
let heavyResource: HeavyResource | null = null;
 
async function getHeavyResource(): Promise<HeavyResource> {
  if (!heavyResource) {
    console.log('Initializing heavy resource (cold start only)');
    heavyResource = await HeavyResource.initialize();
  }
  return heavyResource;
}
 
// The actual function handler
export async function processOrder(
  req: express.Request,
  res: express.Response
): Promise<void> {
  // These use cached/initialized resources
  const secrets = await getSecrets();
  const resource = await getHeavyResource();
  
  const orderId = req.body.orderId;
  
  // Firestore client reused from global scope
  const orderDoc = await firestore
    .collection('orders')
    .doc(orderId)
    .get();
  
  if (!orderDoc.exists) {
    res.status(404).json({ error: 'Order not found' });
    return;
  }
  
  const result = await resource.process(orderDoc.data());
  
  res.status(200).json({ result });
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110

// Eventarc trigger patterns for Cloud Functions
 
import { CloudEvent } from '@google-cloud/functions-framework';
import { StorageObjectData } from '@google-cloud/storage';
 
// Trigger on Cloud Storage object creation
// Deploy: gcloud functions deploy handleNewFile \
//   --gen2 --trigger-bucket=my-bucket --trigger-event=google.cloud.storage.object.v1.finalized
 
export async function handleNewFile(
  event: CloudEvent<StorageObjectData>
): Promise<void> {
  const file = event.data;
  
  console.log(`New file uploaded: ${file?.bucket}/${file?.name}`);
  console.log(`Size: ${file?.size} bytes`);
  console.log(`Content-Type: ${file?.contentType}`);
  
  // CloudEvents metadata
  console.log(`Event ID: ${event.id}`);
  console.log(`Event Time: ${event.time}`);
  console.log(`Event Type: ${event.type}`);
  
  // Process the file
  await processUploadedFile(file);
}
 
// Trigger on Pub/Sub messages
// Deploy: gcloud functions deploy handlePubSubMessage \
//   --gen2 --trigger-topic=my-topic
 
interface OrderMessage {
  orderId: string;
  customerId: string;
  amount: number;
}
 
export async function handlePubSubMessage(
  event: CloudEvent<{ message: { data: string } }>
): Promise<void> {
  // Pub/Sub message data is base64 encoded
  const messageData = Buffer.from(
    event.data?.message.data || '',
    'base64'
  ).toString();
  
  const order: OrderMessage = JSON.parse(messageData);
  
  console.log(`Processing order: ${order.orderId}`);
  
  await processOrder(order);
}
 
// Trigger on Audit Log events (any GCP API call)
// Deploy: gcloud functions deploy auditLogHandler \
//   --gen2 \
//   --trigger-event-filters="type=google.cloud.audit.log.v1.written" \
//   --trigger-event-filters="serviceName=bigquery.googleapis.com" \
//   --trigger-event-filters="methodName=google.cloud.bigquery.v2.JobService.InsertJob"
 
interface AuditLogEvent {
  protoPayload: {
    serviceName: string;
    methodName: string;
    resourceName: string;
    authenticationInfo: {
      principalEmail: string;
    };
  };
}
 
export async function auditLogHandler(
  event: CloudEvent<AuditLogEvent>
): Promise<void> {
  const auditLog = event.data?.protoPayload;
  
  console.log(`Service: ${auditLog?.serviceName}`);
  console.log(`Method: ${auditLog?.methodName}`);
  console.log(`User: ${auditLog?.authenticationInfo.principalEmail}`);
  console.log(`Resource: ${auditLog?.resourceName}`);
  
  // Track sensitive operations, send alerts, etc.
  if (isSecuritySensitive(auditLog?.methodName)) {
    await sendSecurityAlert(auditLog);
  }
}
 
// Trigger on custom events from your applications
// Publish: gcloud eventarc events publish my-custom-channel \
//   --event-type=my.custom.event \
//   --event-data='{"key": "value"}'
 
export async function customEventHandler(
  event: CloudEvent<unknown>
): Promise<void> {
  console.log(`Custom event type: ${event.type}`);
  console.log(`Custom event data: ${JSON.stringify(event.data)}`);
  
  // Route based on event type
  switch (event.type) {
    case 'my.app.order.created':
      await handleOrderCreated(event.data);
      break;
    case 'my.app.order.shipped':
      await handleOrderShipped(event.data);
      break;
    default:
      console.warn(`Unknown event type: ${event.type}`);
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82

// Google Cloud service integrations - seamless authentication
 
import { Firestore } from '@google-cloud/firestore';
import { BigQuery } from '@google-cloud/bigquery';
import { Storage } from '@google-cloud/storage';
import { PubSub } from '@google-cloud/pubsub';
import { VertexAI } from '@google-cloud/vertexai';
import { v1 as vision } from '@google-cloud/vision';
 
// All clients automatically use the function's service account
// No credentials needed in code!
 
const firestore = new Firestore();
const bigquery = new BigQuery();
const storage = new Storage();
const pubsub = new PubSub();
const vertexAI = new VertexAI({ project: process.env.GCP_PROJECT!, location: 'us-central1' });
const visionClient = new vision.ImageAnnotatorClient();
 
// Example: Image processing pipeline
export async function processUploadedImage(
  event: CloudEvent<StorageObjectData>
): Promise<void> {
  const { bucket, name } = event.data!;
  
  // 1. Analyze image with Vision AI
  const [visionResult] = await visionClient.labelDetection(
    `gs://${bucket}/${name}`
  );
  
  const labels = visionResult.labelAnnotations?.map(l => ({
    description: l.description,
    score: l.score
  })) || [];
  
  // 2. Generate description with Vertex AI
  const model = vertexAI.getGenerativeModel({ model: 'gemini-pro-vision' });
  const imageUrl = `gs://${bucket}/${name}`;
  
  const prompt = `Describe this image in one paragraph, focusing on: ${
    labels.slice(0, 5).map(l => l.description).join(', ')
  }`;
  
  const result = await model.generateContent([
    prompt,
    { fileData: { mimeType: 'image/jpeg', fileUri: imageUrl } }
  ]);
  
  const description = result.response.text();
  
  // 3. Store metadata in Firestore
  await firestore.collection('images').doc(name).set({
    bucket,
    path: name,
    labels,
    description,
    processedAt: new Date()
  });
  
  // 4. Log to BigQuery for analytics
  await bigquery
    .dataset('image_analytics')
    .table('processed_images')
    .insert([{
      image_path: `gs://${bucket}/${name}`,
      label_count: labels.length,
      top_label: labels[0]?.description,
      processed_timestamp: new Date().toISOString()
    }]);
  
  // 5. Publish event for downstream consumers
  await pubsub.topic('image-processed').publishMessage({
    data: Buffer.from(JSON.stringify({
      bucket,
      name,
      labels: labels.slice(0, 5),
      description: description.substring(0, 500)
    }))
  });
  
  console.log(`Processed image: ${bucket}/${name}`);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

// Cold start optimization strategies
 
// 1. LAZY INITIALIZATION
// Don't initialize resources until first use
let firestoreClient: Firestore | null = null;
 
function getFirestore(): Firestore {
  if (!firestoreClient) {
    firestoreClient = new Firestore();
  }
  return firestoreClient;
}
 
// 2. MINIMAL DEPENDENCIES
// package.json - only import what you need
// GOOD:
import { Firestore } from '@google-cloud/firestore';
// BAD:
// import * as gcloud from '@google-cloud';  // Imports everything!
 
// 3. BUNDLE OPTIMIZATION (use esbuild or rollup)
// Reduce bundle size dramatically
// tsconfig.json / build config:
// "target": "ES2020",
// "module": "ES2020"
 
// 4. PRECOMPILE TYPESCRIPT
// Deploy compiled JavaScript, not TypeScript
// Avoids runtime transpilation overhead
 
// 5. MINIMUM VIABLE LOGGING IN COLD START
// Defer expensive operations
let initialized = false;
 
export async function handler(req: Request, res: Response): Promise<void> {
  const startTime = Date.now();
  
  if (!initialized) {
    // Minimal cold start initialization
    console.log('Cold start initialization');
    initialized = true;
  }
  
  // Track if this was a cold start
  const coldStart = Date.now() - startTime > 100;
  
  // Actual handler logic
  const result = await processRequest(req);
  
  // Log cold start metric for monitoring
  if (coldStart) {
    console.log(JSON.stringify({
      severity: 'INFO',
      message: 'Cold start completed',
      coldStartDuration: Date.now() - startTime,
      functionName: process.env.FUNCTION_NAME
    }));
  }
  
  res.json(result);
}
 
// 6. MINIMUM INSTANCES (2nd gen only)
// Keep instances warm during business hours
// Deploy: gcloud functions deploy my-function \
//   --gen2 --min-instances=1 --max-instances=100
 
// 7. CONCURRENCY LEVERAGING
// Higher concurrency = more requests served by warm instances
// 10 concurrent requests with concurrency=10 needs only 1 warm instance
// vs 10 instances with concurrency=1

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

// Security patterns for Cloud Functions
 
import * as functions from '@google-cloud/functions-framework';
import { OAuth2Client } from 'google-auth-library';
 
// 1. IAM-authenticated function (default for internal services)
// Deploy: gcloud functions deploy secure-function \
//   --gen2 --no-allow-unauthenticated
 
// Client must include ID token:
// const token = await authClient.getIdToken(targetAudience);
// fetch(url, { headers: { Authorization: `Bearer ${token}` } })
 
// 2. Custom JWT validation for third-party auth
const oauthClient = new OAuth2Client();
 
async function validateIdToken(req: Request): Promise<string | null> {
  const authHeader = req.headers.authorization;
  if (!authHeader?.startsWith('Bearer ')) {
    return null;
  }
  
  const idToken = authHeader.split('Bearer ')[1];
  
  try {
    const ticket = await oauthClient.verifyIdToken({
      idToken,
      audience: process.env.FUNCTION_URL
    });
    
    const payload = ticket.getPayload();
    return payload?.email || null;
  } catch (error) {
    console.error('Token validation failed:', error);
    return null;
  }
}
 
export async function secureEndpoint(
  req: Request,
  res: Response
): Promise<void> {
  const userEmail = await validateIdToken(req);
  
  if (!userEmail) {
    res.status(401).json({ error: 'Unauthorized' });
    return;
  }
  
  // Check authorization
  if (!await isAuthorized(userEmail, req.path)) {
    res.status(403).json({ error: 'Forbidden' });
    return;
  }
  
  // Process authorized request
  const result = await processRequest(req, userEmail);
  res.json(result);
}
 
// 3. Validate incoming webhooks (e.g., Stripe, GitHub)
import crypto from 'crypto';
 
function validateWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}
 
export async function webhookHandler(
  req: Request,
  res: Response
): Promise<void> {
  const signature = req.headers['x-webhook-signature'] as string;
  const payload = JSON.stringify(req.body);
  
  if (!validateWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET!)) {
    res.status(401).json({ error: 'Invalid signature' });
    return;
  }
  
  // Process validated webhook
  await processWebhook(req.body);
  res.status(200).send('OK');
}