Nasajon GCF Utilities

Common errors

• ModuleNotFoundError: No module named 'django'

  cause The `nsj-gcf-utils` library has hard dependencies on Django and Django REST Framework, but these packages were not installed in the environment.
  fix Install the required dependencies: `pip install nsj-gcf-utils Django djangorestframework django-cors-headers` or ensure they are listed in your `requirements.txt`.

• google.api_core.exceptions.PermissionDenied: 7 PERMISSION_DENIED: User lacks permission

  cause The Google Cloud Function's service account does not have the necessary IAM permissions to access the Google Cloud resource (e.g., Firestore database, Cloud Storage bucket, Secret Manager secret) that the library is trying to use.
  fix Grant the appropriate IAM roles to the GCF's service account. For example, if accessing Firestore, add `Cloud Datastore User` (roles/datastore.user) or `Cloud Datastore Editor` (roles/datastore.editor).

• AttributeError: 'NoneType' object has no attribute 'request_id'

  cause This typically occurs when `get_current_function_context()` is called, but the underlying Flask `request` object (or its mock) does not contain the expected headers (like `X-Request-ID`), causing `FunctionContext` properties to remain `None`.
  fix Ensure that the HTTP request object passed to your GCF handler contains the necessary headers (`X-Request-ID`, `X-User-ID`, `X-Entity-ID`, etc.) which `nsj-gcf-utils` expects to populate the context. For local testing, pass a mock request with these headers.

Warnings

• gotcha This library is not a general-purpose Google Cloud Functions utility. It has strong dependencies on Django and Django REST Framework, implying it's intended for specific architectural patterns where a Django/DRF application is deployed as a GCF. Attempting to use it in a pure, minimalist GCF environment without these frameworks will likely lead to `ModuleNotFoundError` or unexpected behavior.
  Fix: Ensure your GCF project includes Django and Django REST Framework in its `requirements.txt` if using this library. Reconsider if `nsj-gcf-utils` is the right tool for pure Python/minimalist GCFs without a Django/DRF backend.
• gotcha Google Cloud service clients (e.g., Firestore, Storage, Secret Manager) initialized by this library will rely on the default Google Cloud authentication mechanism, typically the GCF's associated service account. Incorrect IAM permissions for this service account will lead to `PermissionDenied` errors.
  Fix: Verify that the Google Cloud Function's service account has the necessary IAM roles and permissions (e.g., `roles/datastore.user` for Firestore, `roles/storage.objectViewer` for Storage) for the resources it attempts to access.
• gotcha The `FunctionContext` object populated by `get_current_function_context` relies on specific HTTP headers (e.g., `X-Request-ID`, `X-User-ID`, `X-Entity-ID`) being present in the incoming GCF request. If these headers are missing or not propagated, context properties might be `None` or raise `AttributeError`.
  Fix: Ensure that upstream callers (e.g., API Gateway, other services) are correctly populating these headers. For local testing, mock the `request` object with appropriate headers, as shown in the quickstart.

Install

• pip install nsj-gcf-utils Install stable version

Imports

• get_current_function_context

  from nsj_gcf_utils.objects.function_context import get_current_function_context

• FunctionContext

  from nsj_gcf_utils.objects.function_context import FunctionContext

  This is the class returned by `get_current_function_context`, useful for type hinting.
• get_firestore_client

  from nsj_gcf_utils.firestore import get_firestore_client

• GcfException

  from nsj_gcf_utils.exception import GcfException

Quickstart

This quickstart demonstrates how to retrieve the current function context within a GCF handler. It uses `get_current_function_context` to access request-specific metadata, such as request ID, user ID, and entity ID, which are typically passed via HTTP headers in a Google Cloud Function environment. A mock request object is included to make the example runnable locally, simulating a GCF invocation. Note that Google Cloud service clients (like Firestore) require proper GCP authentication and project setup to function.

import json
from nsj_gcf_utils.objects.function_context import get_current_function_context
from nsj_gcf_utils.exception import GcfException

# Simulate a Flask-like request object for local testing
# In a real GCF environment, 'request' is provided by the framework.
class MockRequest:
    def __init__(self, json_data, headers=None):
        self._json_data = json_data
        self.headers = headers if headers is not None else {}

    @property
    def json(self):
        return self._json_data

    def get_json(self):
        return self._json_data

    def get_data(self):
        return json.dumps(self._json_data).encode('utf-8')


def my_gcf_handler(request):
    try:
        # Get the current function context
        # In GCF, 'request' would be the actual Flask request object.
        context = get_current_function_context(request)

        # Access context properties (these would be populated by GCF headers)
        print(f"Request ID: {context.request_id}")
        print(f"User ID: {context.user_id}")
        print(f"Entity ID: {context.entity_id}")

        return "OK", 200
    except GcfException as e:
        print(f"Error: {e}")
        return str(e), 500
    except Exception as e:
        print(f"Unexpected error: {e}")
        return str(e), 500

# Example usage with a mock request (simulating a GCF invocation)
mock_headers = {
    'X-Request-ID': 'mock-req-123',
    'X-User-ID': 'mock-user-456',
    'X-Entity-ID': 'mock-entity-789'
}
mock_json_payload = {'data': 'some_data'}
mock_request = MockRequest(mock_json_payload, headers=mock_headers)

response, status_code = my_gcf_handler(mock_request)
print(f"\nHandler Response: {response}, Status: {status_code}")

# Example of using Firestore client (requires actual GCP setup)
try:
    # from nsj_gcf_utils.firestore import get_firestore_client
    # firestore_client = get_firestore_client()
    # print("Firestore client initialized successfully.")
    print("\nUncomment Firestore client example for actual GCP interaction.")
except Exception as e:
    print(f"Could not initialize Firestore client (expected outside GCF): {e}")