Merge branch 'main' into @invertase/feat-support-exception-logging

Author: IzaakGough

.github/workflows/ci.yaml

@@ -6,6 +6,9 @@ on:
     branches:
       - main
 
+permissions:
+  contents: read
+
 jobs:
   test:
     runs-on: ubuntu-latest
@@ -15,9 +18,11 @@ jobs:
         python: ["3.10", "3.12"]
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
       - name: Install uv
-        uses: astral-sh/setup-uv@v3
+        uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39 # v3.2.4
         with:
           enable-cache: true
       - name: Set up Python ${{ matrix.python }}
@@ -35,9 +40,11 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
       - name: Install uv
-        uses: astral-sh/setup-uv@v3
+        uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39 # v3.2.4
         with:
           enable-cache: true
       - name: Set up Python
@@ -55,9 +62,11 @@ jobs:
   docs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
       - name: Install uv
-        uses: astral-sh/setup-uv@v3
+        uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39 # v3.2.4
         with:
           enable-cache: true
       - name: Set up Python
@@ -69,7 +78,7 @@ jobs:
         run: |
           mkdir ./docs/build
           uv run ./docs/generate.sh --out=./docs/build/ --pypath=src/
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08 # v4.6.0
         name: Upload Docs Preview
         with:
           name: reference-docs
@@ -78,9 +87,11 @@ jobs:
   format:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
       - name: Install uv
-        uses: astral-sh/setup-uv@v3
+        uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39 # v3.2.4
         with:
           enable-cache: true
       - name: Set up Python
@@ -90,4 +101,4 @@ jobs:
           uv sync
       - name: Check Formatting with ruff
         run: |
-          uv run ruff format --check .
+          uv run ruff format --check .

.github/workflows/release.yaml

@@ -20,6 +20,9 @@ on:
   # Allow workflow to be triggered manually.
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 jobs:
   stage_release:
     # To publish a release, merge the release PR with the label 'release:publish'.
@@ -34,15 +37,17 @@ jobs:
 
     steps:
     - name: Checkout source for staging
-      uses: actions/checkout@v3
+      uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      with:
+        persist-credentials: false
 
     - name: Set up Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@42375524e23c412d93fb67b49958b491fce71c38 # v5.4.0
       with:
         python-version: '3.10'
 
     - name: Install uv
-      uses: astral-sh/setup-uv@v3
+      uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39 # v3.2.4
       with:
         enable-cache: true
 
@@ -62,7 +67,7 @@ jobs:
     # Attach the packaged artifacts to the workflow output. These can be manually
     # downloaded for later inspection if necessary.
     - name: Archive artifacts
-      uses: actions/upload-artifact@v4
+      uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08 # v4.6.0
       with:
         name: dist
         path: dist/
@@ -92,11 +97,13 @@ jobs:
 
     steps:
     - name: Checkout source for publish
-      uses: actions/checkout@v4
+      uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      with:
+        persist-credentials: false
 
     # Download the artifacts created by the stage_release job.
     - name: Download release candidates
-      uses: actions/download-artifact@v4.1.7
+      uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
       with:
         name: dist
         path: dist
@@ -111,7 +118,7 @@ jobs:
     - name: Create release tag
       # Skip creating a release tag for prereleases
       if: (!contains(github.event.pull_request.labels.*.name, 'release:prerelease'))
-      uses: fleskesvor/create-release@1a72e235c178bf2ae6c51a8ae36febc24568c5fe
+      uses: fleskesvor/create-release@1a72e235c178bf2ae6c51a8ae36febc24568c5fe # zizmor: ignore[unpinned-uses]
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       with:
@@ -122,4 +129,4 @@ jobs:
         prerelease: false
 
     - name: Publish to Pypi
-      uses: pypa/gh-action-pypi-publish@release/v1
+      uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

pyproject.toml

@@ -28,7 +28,7 @@ dependencies = [
   "cloudevents>=1.2.0,<2.0.0",
   "flask-cors>=3.0.10",
   "pyjwt[crypto]>=2.5.0",
-  "google-events==0.5.0",
+  "google-events>=0.5.0,<1.0.0",
   "google-cloud-firestore>=2.11.0",
   "tzdata>=2024.1",
 ]

src/firebase_functions/firestore_fn.py

@@ -221,7 +221,7 @@ def _firestore_endpoint_handler(
         func(database_event_with_auth_context)
     else:
         # mypy cannot infer that the event type is correct, hence the cast
-        _typing.cast(_C1 | _C2, func)(database_event)
+        _typing.cast(_C1 | _C2, func)(database_event)  # type: ignore[arg-type]
 
 
 @_util.copy_func_kwargs(FirestoreOptions)

src/firebase_functions/options.py

@@ -254,10 +254,11 @@ class RuntimeOptions:
     to the value "gcf_gen1"
     """
 
-    vpc_connector: str | _util.Sentinel | None = None
+    vpc_connector: str | Expression[str] | _util.Sentinel | None = None
     """
     Connect function to specified VPC connector.
-    A value of ``RESET_VALUE`` removes the VPC connector.
+    Accepts a plain string, an ``Expression[str]`` (e.g. a ``StringParam`` or
+    ternary expression), or ``RESET_VALUE`` to remove the VPC connector.
     """
 
     vpc_connector_egress_settings: VpcEgressSetting | _util.Sentinel | None = None
@@ -1254,8 +1255,8 @@ def set_global_options(
     max_instances: int | Expression[int] | _util.Sentinel | None = None,
     concurrency: int | Expression[int] | _util.Sentinel | None = None,
     cpu: int | _typing.Literal["gcf_gen1"] | _util.Sentinel = "gcf_gen1",
-    vpc_connector: str | None = None,
-    vpc_connector_egress_settings: VpcEgressSetting | None = None,
+    vpc_connector: str | Expression[str] | _util.Sentinel | None = None,
+    vpc_connector_egress_settings: VpcEgressSetting | _util.Sentinel | None = None,
     service_account: str | _util.Sentinel | None = None,
     ingress: IngressSetting | _util.Sentinel | None = None,
     labels: dict[str, str] | None = None,

tests/conftest.py

@@ -0,0 +1,30 @@
+# Copyright 2026 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+Pytest configuration and shared fixtures for the test suite.
+"""
+
+import pytest
+
+from firebase_functions import params
+
+# pylint: disable=protected-access
+
+
+@pytest.fixture(autouse=True)
+def _cleanup_params():
+    """Clear the global params registry so each test runs with a clean state."""
+    params._params.clear()
+    yield
+    params._params.clear()

tests/test_options.py

@@ -15,6 +15,7 @@
 Options unit tests.
 """
 
+import pytest
 from pytest import raises
 
 from firebase_functions import alerts_fn, https_fn, options, params
@@ -41,6 +42,15 @@ def asamplefunctionpreserved(_):
     return "hello world"
 
 
+@pytest.fixture(autouse=True)
+def _cleanup_global_options():
+    """Reset global options so each test runs with a clean state."""
+    original_options = options._GLOBAL_OPTIONS
+    options._GLOBAL_OPTIONS = options.RuntimeOptions()
+    yield
+    options._GLOBAL_OPTIONS = original_options
+
+
 def test_set_global_options():
     """
     Testing if setting a global option internally change the values.
@@ -64,6 +74,30 @@ def test_global_options_merged_with_provider_options():
     )
 
 
+@pytest.mark.parametrize(
+    "vpc_connector_expr_factory",
+    [
+        lambda: params.StringParam("VPC_CONNECTOR"),
+        lambda: params.BoolParam("USE_VPC").equals(True).then("my-vpc", ""),
+    ],
+)
+def test_set_global_options_accepts_vpc_connector_expression(vpc_connector_expr_factory):
+    vpc_connector_expr = vpc_connector_expr_factory()
+    options.set_global_options(vpc_connector=vpc_connector_expr)
+
+    assert options._GLOBAL_OPTIONS.vpc_connector == vpc_connector_expr, (
+        "global vpc_connector expression was not stored"
+    )
+
+    https_options = options.HttpsOptions()
+    endpoint = https_options._endpoint(func_name="test_vpc_global")
+
+    assert endpoint.vpc is not None, "vpc block was not set on endpoint"
+    assert endpoint.vpc["connector"] == str(vpc_connector_expr), (
+        "global vpc_connector Expression[str] was not applied to the endpoint"
+    )
+
+
 def test_https_options_removes_cors():
     """
     Testing _HttpsOptions strips out the 'cors' property when converted to a dict.
@@ -206,6 +240,48 @@ def test_invoker_with_no_element_throws():
         options.HttpsOptions(invoker=[])._endpoint(func_name="test")
 
 
+@pytest.mark.parametrize(
+    "vpc_connector_expr_factory",
+    [
+        lambda: params.StringParam("VPC_CONNECTOR"),
+        lambda: params.BoolParam("USE_VPC").equals(True).then("my-vpc", ""),
+    ],
+)
+def test_vpc_connector_accepts_expression(vpc_connector_expr_factory):
+    vpc_connector_expr = vpc_connector_expr_factory()
+    https_options = options.HttpsOptions(vpc_connector=vpc_connector_expr)
+    https_options_dict = https_options._asdict_with_global_options()
+
+    # The options dict should contain the CEL string representation for the expression.
+    assert https_options_dict["vpc_connector"] == str(vpc_connector_expr), (
+        "vpc_connector expression was not converted to CEL string"
+    )
+
+    # The generated endpoint should map the resolved vpc_connector into the vpc block.
+    endpoint = https_options._endpoint(func_name="test_vpc")
+    assert endpoint.vpc is not None, "vpc block was not set on endpoint"
+    assert endpoint.vpc["connector"] == str(vpc_connector_expr), (
+        "vpc connector was not set from vpc_connector Expression[str]"
+    )
+
+
+def test_vpc_connector_expression_with_egress_settings():
+    vpc_connector_expr = params.StringParam("VPC_CONNECTOR")
+    https_options = options.HttpsOptions(
+        vpc_connector=vpc_connector_expr,
+        vpc_connector_egress_settings=options.VpcEgressSetting.ALL_TRAFFIC,
+    )
+
+    endpoint = https_options._endpoint(func_name="test_vpc_egress")
+    assert endpoint.vpc is not None, "vpc block was not set on endpoint"
+    assert endpoint.vpc["connector"] == str(vpc_connector_expr), (
+        "vpc connector was not set from vpc_connector Expression[str]"
+    )
+    assert endpoint.vpc.get("egressSettings") == options.VpcEgressSetting.ALL_TRAFFIC.value, (
+        "egressSettings was not set alongside an Expression[str] vpc_connector"
+    )
+
+
 def _assert_alert_endpoint_options(endpoint, expected_alert_type, expect_app_id: str | None = None):
     assert endpoint.region == ["europe-west1"]
     assert endpoint.maxInstances == 1