# googlecloudplatform/service-extensions architecture

> Architecture diagram of the GitHub repository googlecloudplatform/service-extensions, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/googlecloudplatform/service-extensions
- Repository: https://github.com/googlecloudplatform/service-extensions

## Overview

This repository is a collection of Google Cloud Service Extensions recipes, not one runtime application. Its principal workflow is a load balancer invoking a user-managed gRPC callout during request processing, where an extension handles HTTP or network data and returns processing actions. It also provides Wasm plugin samples that run inline in the networking data path. The tree and excerpts establish the server and example boundaries; unsampled example and plugin internals are represented only at directory level, so their detailed call relationships are not inferred.

Main entry points: [`callouts/python/extproc/l4_example/network_basic/network_service_callout_example.py`](https://github.com/googlecloudplatform/service-extensions/blob/main/callouts/python/extproc/l4_example/network_basic/network_service_callout_example.py) (Layer 4 example), [`callouts/python/extproc/service/network_callout_server.py`](https://github.com/googlecloudplatform/service-extensions/blob/main/callouts/python/extproc/service/network_callout_server.py) (Network callout), [`callouts/python/extproc/service/callout_server.py`](https://github.com/googlecloudplatform/service-extensions/blob/main/callouts/python/extproc/service/callout_server.py) (gRPC callout), [`callouts/python/extproc/service/command_line_tools.py`](https://github.com/googlecloudplatform/service-extensions/blob/main/callouts/python/extproc/service/command_line_tools.py) (Server options)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_callouts["Callout servers"]
  node_grpc_callout["gRPC callout<br/>[callout_server.py]"]
  node_network_callout["Network callout"]
  node_callout_options["Server options"]
  node_go_server["Go gRPC server<br/>[callout_server.go]"]
  node_go_mutations["Go mutation tools<br/>[callout_tools.go]"]
  node_java_server["Java gRPC server"]
  node_java_mutations["Java mutation tools"]
  node_java_tls["Java TLS utilities<br/>[SslUtils.java]"]
end

subgraph group_extproc_examples["HTTP processing examples"]
  node_http_recipes["HTTP callout recipes"]
  node_network_example["Layer 4 example"]
  node_go_recipes["Go callout recipes"]
  node_java_recipes["Java callout recipes"]
end

subgraph group_auth_examples["Authorization examples"]
  node_auth_server["Authorization server<br/>[callout_server.py]"]
  node_auth_recipes["Authorization recipes"]
end

subgraph group_plugins["Wasm plugins"]
  node_plugin_runtime{{"Managed Wasm runtime"}}
  node_ab_testing["A/B testing sample"]
  node_ad_insertion["Ad insertion sample"]
end

node_load_balancer(("Cloud load balancer"))

node_load_balancer -->|"makes gRPC calls"| node_grpc_callout
node_load_balancer -.->|"processes network data"| node_network_callout
node_network_example -->|"parses options"| node_callout_options
node_network_example -->|"subclasses"| node_network_callout
node_load_balancer -.->|"checks authorization"| node_auth_server
node_plugin_runtime -.->|"runs sample"| node_ab_testing
node_plugin_runtime -.->|"runs sample"| node_ad_insertion
node_plugin_runtime -->|"inserts inline code"| node_load_balancer

click node_grpc_callout "https://github.com/googlecloudplatform/service-extensions/blob/main/callouts/python/extproc/service/callout_server.py"
click node_network_callout "https://github.com/googlecloudplatform/service-extensions/blob/main/callouts/python/extproc/service/network_callout_server.py"
click node_callout_options "https://github.com/googlecloudplatform/service-extensions/blob/main/callouts/python/extproc/service/command_line_tools.py"
click node_go_server "https://github.com/googlecloudplatform/service-extensions/blob/main/callouts/go/extproc/internal/server/callout_server.go"
click node_go_mutations "https://github.com/googlecloudplatform/service-extensions/blob/main/callouts/go/extproc/pkg/utils/callout_tools.go"
click node_java_server "https://github.com/googlecloudplatform/service-extensions/blob/main/callouts/java/service-callout/src/main/java/service/ServiceCallout.java"
click node_java_mutations "https://github.com/googlecloudplatform/service-extensions/blob/main/callouts/java/service-callout/src/main/java/service/ServiceCalloutTools.java"
click node_java_tls "https://github.com/googlecloudplatform/service-extensions/blob/main/callouts/java/service-callout/src/main/java/utils/SslUtils.java"
click node_http_recipes "https://github.com/googlecloudplatform/service-extensions/tree/main/callouts/python/extproc/example"
click node_network_example "https://github.com/googlecloudplatform/service-extensions/blob/main/callouts/python/extproc/l4_example/network_basic/network_service_callout_example.py"
click node_go_recipes "https://github.com/googlecloudplatform/service-extensions/tree/main/callouts/go/extproc/examples"
click node_java_recipes "https://github.com/googlecloudplatform/service-extensions/tree/main/callouts/java/service-callout/src/main/java/example"
click node_auth_server "https://github.com/googlecloudplatform/service-extensions/blob/main/callouts/python/extauthz/service/callout_server.py"
click node_auth_recipes "https://github.com/googlecloudplatform/service-extensions/tree/main/callouts/python/extauthz/example"
click node_ab_testing "https://github.com/googlecloudplatform/service-extensions/tree/main/plugins/samples/ab_testing"
click node_ad_insertion "https://github.com/googlecloudplatform/service-extensions/tree/main/plugins/samples/ad_insertion"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_grpc_callout,node_network_callout,node_callout_options,node_go_server,node_go_mutations,node_java_server,node_java_mutations,node_java_tls toneBlue
class node_http_recipes,node_network_example,node_go_recipes,node_java_recipes toneAmber
class node_auth_server,node_auth_recipes toneMint
class node_plugin_runtime,node_ab_testing,node_ad_insertion toneRose
class node_load_balancer toneIndigo
```

## Components

### Callout servers

- [gRPC callout](https://github.com/googlecloudplatform/service-extensions/blob/main/callouts/python/extproc/service/callout_server.py): `callouts/python/extproc/service/callout_server.py`
- [Network callout](https://github.com/googlecloudplatform/service-extensions/blob/main/callouts/python/extproc/service/network_callout_server.py): `callouts/python/extproc/service/network_callout_server.py`
- [Server options](https://github.com/googlecloudplatform/service-extensions/blob/main/callouts/python/extproc/service/command_line_tools.py): `callouts/python/extproc/service/command_line_tools.py`
- [Go gRPC server](https://github.com/googlecloudplatform/service-extensions/blob/main/callouts/go/extproc/internal/server/callout_server.go): `callouts/go/extproc/internal/server/callout_server.go`
- [Go mutation tools](https://github.com/googlecloudplatform/service-extensions/blob/main/callouts/go/extproc/pkg/utils/callout_tools.go): `callouts/go/extproc/pkg/utils/callout_tools.go`
- [Java gRPC server](https://github.com/googlecloudplatform/service-extensions/blob/main/callouts/java/service-callout/src/main/java/service/ServiceCallout.java): `callouts/java/service-callout/src/main/java/service/ServiceCallout.java`
- [Java mutation tools](https://github.com/googlecloudplatform/service-extensions/blob/main/callouts/java/service-callout/src/main/java/service/ServiceCalloutTools.java): `callouts/java/service-callout/src/main/java/service/ServiceCalloutTools.java`
- [Java TLS utilities](https://github.com/googlecloudplatform/service-extensions/blob/main/callouts/java/service-callout/src/main/java/utils/SslUtils.java): `callouts/java/service-callout/src/main/java/utils/SslUtils.java`

### HTTP processing examples

- [HTTP callout recipes](https://github.com/googlecloudplatform/service-extensions/tree/main/callouts/python/extproc/example): `callouts/python/extproc/example`
- [Layer 4 example](https://github.com/googlecloudplatform/service-extensions/blob/main/callouts/python/extproc/l4_example/network_basic/network_service_callout_example.py): `callouts/python/extproc/l4_example/network_basic/network_service_callout_example.py`
- [Go callout recipes](https://github.com/googlecloudplatform/service-extensions/tree/main/callouts/go/extproc/examples): `callouts/go/extproc/examples`
- [Java callout recipes](https://github.com/googlecloudplatform/service-extensions/tree/main/callouts/java/service-callout/src/main/java/example): `callouts/java/service-callout/src/main/java/example`

### Authorization examples

- [Authorization server](https://github.com/googlecloudplatform/service-extensions/blob/main/callouts/python/extauthz/service/callout_server.py): `callouts/python/extauthz/service/callout_server.py`
- [Authorization recipes](https://github.com/googlecloudplatform/service-extensions/tree/main/callouts/python/extauthz/example): `callouts/python/extauthz/example`

### Wasm plugins

- **Managed Wasm runtime**
- [A/B testing sample](https://github.com/googlecloudplatform/service-extensions/tree/main/plugins/samples/ab_testing): `plugins/samples/ab_testing`
- [Ad insertion sample](https://github.com/googlecloudplatform/service-extensions/tree/main/plugins/samples/ad_insertion): `plugins/samples/ad_insertion`

### Other components

- **Cloud load balancer**

## Connections

- Cloud load balancer → gRPC callout: makes gRPC calls (evidence: `README.md`)
- Cloud load balancer → Network callout: processes network data
- Layer 4 example → Server options: parses options (evidence: `callouts/python/extproc/l4_example/network_basic/network_service_callout_example.py`)
- Layer 4 example → Network callout: subclasses (evidence: `callouts/python/extproc/l4_example/network_basic/network_service_callout_example.py`)
- Cloud load balancer → Authorization server: checks authorization
- Managed Wasm runtime → A/B testing sample: runs sample
- Managed Wasm runtime → Ad insertion sample: runs sample
- Managed Wasm runtime → Cloud load balancer: inserts inline code (evidence: `README.md`)