{"id":34528961,"url":"https://github.com/linuxfoundation/lfx-v2-mailing-list-service","last_synced_at":"2026-04-20T22:01:16.923Z","repository":{"id":309511544,"uuid":"1016239415","full_name":"linuxfoundation/lfx-v2-mailing-list-service","owner":"linuxfoundation","description":"LFX v2 Platform Mailing List Service","archived":false,"fork":false,"pushed_at":"2026-04-13T19:36:09.000Z","size":1874,"stargazers_count":0,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-13T20:26:39.751Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/linuxfoundation.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-08T17:42:55.000Z","updated_at":"2026-04-13T19:36:12.000Z","dependencies_parsed_at":"2025-09-01T11:18:47.776Z","dependency_job_id":"73cdad2e-2a12-48c9-b264-8851955405b7","html_url":"https://github.com/linuxfoundation/lfx-v2-mailing-list-service","commit_stats":null,"previous_names":["linuxfoundation/lfx-v2-mailing-list-service"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/linuxfoundation/lfx-v2-mailing-list-service","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linuxfoundation%2Flfx-v2-mailing-list-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linuxfoundation%2Flfx-v2-mailing-list-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linuxfoundation%2Flfx-v2-mailing-list-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linuxfoundation%2Flfx-v2-mailing-list-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/linuxfoundation","download_url":"https://codeload.github.com/linuxfoundation/lfx-v2-mailing-list-service/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linuxfoundation%2Flfx-v2-mailing-list-service/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32067626,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-20T21:26:33.338Z","status":"ssl_error","status_checked_at":"2026-04-20T21:26:22.081Z","response_time":94,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-24T05:26:15.671Z","updated_at":"2026-04-20T22:01:16.917Z","avatar_url":"https://github.com/linuxfoundation.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LFX V2 Mailing List Service\n\nThe LFX v2 Mailing List Service is a lightweight proxy microservice that delegates all GroupsIO operations to the ITX HTTP API. Built with Go and the Goa framework, it authenticates via Auth0 M2M OAuth2, translates LFX v2 UUIDs to v1 SFIDs via NATS request/reply, and forwards requests to the ITX backend.\n\n## 🚀 Quick Start\n\n### For Deployment (Helm)\n\nBoth flows below require the Kubernetes secret to be created first. If the `lfx` namespace doesn't exist yet, create it:\n\n```bash\nkubectl create namespace lfx\n```\n\nThen create the secret (values are in 1Password → **LFX V2** vault → **LFX Platform Chart Values Secrets - Local Development**):\n\n```bash\nkubectl create secret generic lfx-v2-mailing-list-service -n lfx \\\n  --from-literal=ITX_CLIENT_ID=\"\u003cvalue-from-1password\u003e\" \\\n  --from-literal=ITX_CLIENT_PRIVATE_KEY=\"\u003cvalue-from-1password\u003e\" \\\n  --from-literal=ITX_AUTH0_DOMAIN=\"\u003cvalue-from-1password\u003e\" \\\n  --from-literal=ITX_AUDIENCE=\"\u003cvalue-from-1password\u003e\" \\\n  --from-literal=ITX_BASE_URL=\"\u003cvalue-from-1password\u003e\"\n```\n\n#### Deploy from GHCR (no local code changes)\n\nPulls the published image from GHCR — no local build required:\n\n```bash\nmake helm-install\n```\n\n#### Deploy a local build (with code changes)\n\nBuild the image locally, then install using the local values override (which sets `pullPolicy: Never` and the local image repository). Copy the example file first — `values.local.yaml` is not tracked by git so it is safe to modify:\n\n```bash\ncp charts/lfx-v2-mailing-list-service/values.local.example.yaml \\\n   charts/lfx-v2-mailing-list-service/values.local.yaml\n\nmake docker-build\nmake helm-install-local\n```\n\n### For Local Development\n\n1. **Prerequisites**\n   - Go 1.24+ installed\n   - Make installed\n   - Docker (optional, for containerized development)\n   - NATS server running (required for ID translation)\n\n2. **Clone and Setup**\n\n   ```bash\n   git clone https://github.com/linuxfoundation/lfx-v2-mailing-list-service.git\n   cd lfx-v2-mailing-list-service\n\n   # Install dependencies and generate API code\n   make deps\n   make apigen\n   ```\n\n3. **Configure Environment**\n\n   ```bash\n   # For local development with mock translator (no NATS required)\n   export TRANSLATOR_SOURCE=mock\n   export TRANSLATOR_MAPPINGS_FILE=translator_mappings.yaml\n   export AUTH_SOURCE=mock\n   export JWT_AUTH_DISABLED_MOCK_LOCAL_PRINCIPAL=\"test-admin\"\n   export LOG_LEVEL=debug\n\n   # ITX proxy credentials (required even locally unless you stub the proxy)\n   # Get ITX_CLIENT_ID and ITX_CLIENT_PRIVATE_KEY from 1Password → LFX V2 vault →\n   # LFX Platform Chart Values Secrets - Local Development\n   export ITX_BASE_URL=\"https://api.dev.itx.linuxfoundation.org\"\n   export ITX_CLIENT_ID=\"your-client-id\"\n   export ITX_CLIENT_PRIVATE_KEY=\"$(cat tmp/local.private.key)\"\n   export ITX_AUTH0_DOMAIN=\"linuxfoundation-dev.auth0.com\"\n   export ITX_AUDIENCE=\"https://api.dev.itx.linuxfoundation.org/\"\n   ```\n\n4. **Run the Service**\n\n   ```bash\n   make run\n   ```\n\n## 🏗️ Architecture\n\nThe service is a thin proxy layer built using clean architecture:\n\n- **API Layer**: Goa-generated HTTP handlers and OpenAPI specifications\n- **Service Layer**: Orchestrators that resolve v2 UUIDs to v1 SFIDs and forward calls to the ITX proxy\n- **Domain Layer**: Core business models, typed domain errors, and port interfaces\n- **Infrastructure Layer**: ITX HTTP proxy client (Auth0 M2M), NATS ID translator, and JWT authentication\n\n### Key Features\n\n- **ITX Proxy**: All GroupsIO operations (services, mailing lists, members) are delegated to the ITX HTTP API\n- **Auth0 M2M Authentication**: ITX requests authenticated via private-key JWT assertion with token caching via `oauth2.ReuseTokenSource`\n- **ID Translation**: Transparent v2 UUID ↔ v1 SFID mapping via NATS request/reply to the v1-sync-helper service\n- **GroupsIO Service Management**: List, get, create, update, delete, and find-parent operations for GroupsIO services\n- **Mailing List Management**: Full lifecycle management including list count and member count endpoints\n- **Member Management**: Add, get, update, delete, invite, and subscriber-check operations\n- **JWT Authentication**: Secure API access via Heimdall integration\n- **Mock Mode**: Complete testing capability without real ITX or NATS dependencies\n- **OpenAPI Documentation**: Auto-generated API specifications\n- **Comprehensive Testing**: Unit test coverage with mocks\n- **Health Checks**: Built-in `/livez` and `/readyz` endpoints for Kubernetes probes\n- **Structured Logging**: JSON-formatted logs with contextual information using Go's slog package\n- **v1→v2 Data Stream**: Consumes DynamoDB change events and publishes them to the indexer and FGA-sync services\n\n## 📁 Project Structure\n\n```bash\nlfx-v2-mailing-list-service/\n├── cmd/                            # Application entry points\n│   └── mailing-list-api/           # Main API server\n│       ├── design/                 # Goa API design files\n│       │   ├── mailing_list.go     # Service and endpoint definitions\n│       │   └── type.go             # Type definitions and data structures\n│       ├── eventing/               # v1→v2 data stream event processing\n│       │   ├── event_processor.go  # JetStream consumer lifecycle\n│       │   └── handler.go          # Key-prefix router (delegates to internal/service)\n│       ├── service/                # GOA service implementations and providers\n│       │   ├── mailing_list_api.go # GOA service implementation\n│       │   ├── providers.go        # Dependency initialization (auth, translator, ITX config)\n│       │   └── converters.go       # Domain ↔ GOA type converters\n│       ├── data_stream.go          # Data stream startup wiring and env config\n│       ├── main.go                 # Application entry point\n│       └── http.go                 # HTTP server setup\n├── charts/                         # Helm chart for Kubernetes deployment\n│   └── lfx-v2-mailing-list-service/\n│       ├── templates/              # Kubernetes resource templates\n│       ├── values.yaml             # Production configuration\n│       └── values.local.yaml       # Local development configuration\n├── docs/                           # Additional documentation\n│   └── event-processing.md         # v1→v2 data stream event processing\n├── gen/                            # Generated code (DO NOT EDIT)\n│   ├── http/                       # HTTP transport layer\n│   │   ├── openapi.yaml            # OpenAPI 2.0 specification\n│   │   └── openapi3.yaml           # OpenAPI 3.0 specification\n│   └── mailing_list/               # Service interfaces\n├── internal/                       # Private application code\n│   ├── domain/                     # Business domain layer\n│   │   ├── errors.go               # Typed domain errors (DomainError with constructors)\n│   │   ├── model/                  # Domain models (GroupsIOService, GroupsIOMailingList, GrpsIOMember)\n│   │   └── port/                   # Repository and service interfaces\n│   │       ├── translator.go       # Translator interface (MapID v2↔v1)\n│   │       └── mapping_store.go    # MappingReader / MappingWriter / MappingReaderWriter\n│   ├── service/                    # Service layer implementation\n│   │   ├── grpsio_service_reader.go         # Service reader orchestrator\n│   │   ├── grpsio_service_writer.go         # Service writer orchestrator\n│   │   ├── grpsio_mailing_list_reader.go    # Mailing list reader orchestrator\n│   │   ├── grpsio_mailing_list_writer.go    # Mailing list writer orchestrator\n│   │   ├── grpsio_member_reader.go          # Member reader orchestrator\n│   │   ├── grpsio_member_writer.go          # Member writer orchestrator\n│   │   ├── datastream_service_handler.go    # v1-sync service transform + publish\n│   │   ├── datastream_subgroup_handler.go   # v1-sync mailing list transform + publish\n│   │   └── datastream_member_handler.go     # v1-sync member transform + publish\n│   ├── infrastructure/             # Infrastructure layer\n│   │   ├── auth/                   # JWT authentication\n│   │   ├── proxy/                  # ITX HTTP proxy client\n│   │   │   ├── itx.go              # ITX client (implements all GroupsIO port interfaces)\n│   │   │   ├── types.go            # Wire types for ITX API requests/responses\n│   │   │   └── converters.go       # Domain ↔ wire type converters\n│   │   ├── nats/                   # NATS messaging and ID translation\n│   │   │   ├── translator.go       # NATS request/reply ID translator\n│   │   │   ├── mapping_store.go    # MappingReaderWriter backed by JetStream KV\n│   │   │   ├── messaging_publish.go # Message publishing\n│   │   │   └── client.go           # NATS connection management\n│   │   └── mock/                   # Mock implementations for testing\n│   │       ├── auth.go             # Mock authentication\n│   │       └── translator.go       # Mock ID translator (file-backed YAML mappings)\n│   └── middleware/                 # HTTP middleware components\n│       ├── authorization.go        # JWT-based authorization\n│       └── request_id.go           # Request ID injection\n├── pkg/                            # Public packages\n│   ├── constants/                  # Application constants\n│   │   ├── context.go              # Context keys\n│   │   ├── global.go               # Global constants\n│   │   ├── storage.go              # Storage bucket names\n│   │   └── subjects.go             # NATS subject definitions\n│   ├── errors/                     # Error types\n│   └── auth/                       # Auth0 token source helpers\n├── Dockerfile                      # Container build configuration\n├── Makefile                        # Build and development commands\n├── CLAUDE.md                       # Claude Code assistant instructions\n└── go.mod                          # Go module definition\n```\n\n## Committee–Mailing List Sync\n\nThis service does not implement committee-to-mailing-list member synchronization. That sync is fully handled by the system this service proxies to (the ITX/v1 backend).\n\nThe sync logic works as follows:\n\n- **When a mailing list is created** with committees configured, all matching members from each committee are immediately synced into the new list.\n- **When a mailing list is updated**, the service compares the old and new committee configurations and acts on three types of changes:\n  - *Added committee*: the committee's members are fully synced into the list.\n  - *Removed committee*: all committee-type members from that committee are removed from the list.\n  - *Modified committee*: if the `AllowedVotingStatuses` filters changed, members who no longer match are removed and members who now match are added.\n\nBecause this service reuses the same database and infrastructure as the proxied backend, this sync loop is already closed and no additional implementation is needed here.\n\n## Committee Member Sync\n\n- **When a committee member is added**, the member is subscribed to all linked mailing lists they are eligible for based on the list's voting status filters.\n- **When a committee member is removed**, the member is unsubscribed from all private mailing lists linked to that committee. Public lists are not affected.\n- **When a committee is deleted**, its association with linked mailing lists is cleared. Existing members are left as-is — no one is removed.\n- **When a committee association or its filters are updated** on a mailing list, the membership is reconciled: members who now match are added, and members who no longer match are removed (private lists only).\n\nBecause this service reuses the same database and infrastructure as the proxied backend, this sync loop is already closed and no additional implementation is needed here.\n\n---\n\n## 📚 Additional Documentation\n\n| Document | Description |\n| --- | --- |\n| [docs/api-endpoints.md](docs/api-endpoints.md) | Full list of API endpoints with method, path, and curl examples |\n| [docs/event-processing.md](docs/event-processing.md) | v1→v2 data stream: how DynamoDB change events are consumed, transformed, and published to the indexer and FGA-sync services |\n| [docs/fga-contract.md](docs/fga-contract.md) | Authoritative reference for all FGA sync messages (NATS subjects, payloads, and trigger conditions) |\n\n## 🛠️ Development\n\n### Prerequisites\n\n- Go 1.24+\n- Make\n- Git\n\n### Getting Started\n\n1. **Install Dependencies**\n\n   ```bash\n   make deps\n   ```\n\n   This installs:\n   - Go module dependencies\n   - Goa CLI for code generation\n\n2. **Generate API Code**\n\n   ```bash\n   make apigen\n   ```\n\n   Generates HTTP transport, client, and OpenAPI documentation from design files.\n\n3. **Build the Application**\n\n   ```bash\n   make build\n   ```\n\n   Creates the binary in `bin/lfx-v2-mailing-list-service`.\n\n### Development Workflow\n\n#### Running the Service\n\n```bash\n# Run with auto-regeneration\nmake run\n\n# Build and run binary\nmake build\n./bin/lfx-v2-mailing-list-service\n```\n\n#### Code Quality\n\n**Always run these before committing:**\n\n```bash\n# Run linter\nmake lint\n\n# Run all tests\nmake test\n\n# Run complete pipeline (setup + lint + test + build)\nmake all\n```\n\n#### Testing\n\n```bash\n# Run all tests with race detection and coverage\nmake test\n\n# View coverage report\ngo tool cover -html=coverage.out\n```\n\n**Writing Tests:**\n\n- Place test files alongside source files with `_test.go` suffix\n- Use table-driven tests for multiple test cases\n- Mock external dependencies using the provided mock interfaces in `internal/infrastructure/mock/`\n- Achieve high test coverage (aim for \u003e80%)\n- Test both happy path and error cases\n\nExample test structure:\n\n```go\nfunc TestServiceMethod(t *testing.T) {\n    tests := []struct {\n        name        string\n        input       InputType\n        setupMocks  func(*MockRepository)\n        expected    ExpectedType\n        expectError bool\n    }{\n        // Test cases here\n    }\n\n    for _, tt := range tests {\n        t.Run(tt.name, func(t *testing.T) {\n            // Test implementation\n        })\n    }\n}\n```\n\n#### API Development\n\nWhen modifying the API:\n\n1. **Update Design Files** in `cmd/mailing-list-api/design/` directory\n2. **Regenerate Code**:\n\n   ```bash\n   make apigen\n   ```\n\n3. **Run Tests** to ensure nothing breaks:\n\n   ```bash\n   make test\n   ```\n\n4. **Update Service Implementation** in `cmd/mailing-list-api/service/`\n\n#### ITX Proxy Architecture\n\nAll GroupsIO operations are delegated to the ITX HTTP API. The proxy layer handles Auth0 M2M token acquisition and transparent v2 UUID → v1 SFID translation.\n\n**Authentication:**\n\n```go\n// ITX proxy uses Auth0 private-key JWT assertion with token caching\ntokenSource := pkgauth.NewAuth0TokenSource(ctx, authConfig, config.Audience, itxScope)\noauthHTTPClient := oauth2.NewClient(ctx, oauth2.ReuseTokenSource(nil, tokenSource))\n```\n\n**ID Translation:**\n\n```go\n// Orchestrators translate v2 UUIDs to v1 SFIDs before forwarding to ITX\nsfid, err := translator.MapID(ctx, constants.TranslationSubjectProject,\n    constants.TranslationDirectionV2ToV1, projectUID)\n```\n\n**Configuration Modes:**\n\n- **Production**: `TRANSLATOR_SOURCE=nats` — translates via NATS request/reply to the v1-sync-helper\n- **Testing**: `TRANSLATOR_SOURCE=mock` — loads mappings from a local YAML file (`TRANSLATOR_MAPPINGS_FILE`)\n\n### Available Make Targets\n\n| Target | Description |\n|--------|-------------|\n| `make all` | Complete build pipeline (setup, lint, test, build) |\n| `make deps` | Install dependencies and Goa CLI |\n| `make setup` | Setup development environment |\n| `make setup-dev` | Install development tools (golangci-lint) |\n| `make apigen` | Generate API code from design files |\n| `make build` | Build the binary |\n| `make run` | Run the service locally |\n| `make test` | Run unit tests with race detection |\n| `make lint` | Run code linter |\n| `make clean` | Remove build artifacts |\n| `make docker-build` | Build Docker image |\n| `make docker-run` | Run Docker container locally |\n| `make helm-install` | Install Helm chart |\n| `make helm-install-local` | Install with mock authentication |\n| `make helm-templates` | Print Helm templates |\n| `make helm-uninstall` | Uninstall Helm chart |\n\n## 🧪 Testing\n\n### Running Tests\n\n```bash\n# Run all tests\nmake test\n\n# Run specific package tests\ngo test -v ./internal/service/...\n\n# Run with coverage\ngo test -v -race -coverprofile=coverage.out ./...\ngo tool cover -html=coverage.out\n```\n\n### Test Structure\n\nThe project follows Go testing best practices:\n\n- **Unit Tests**: Test individual components in isolation\n- **Integration Tests**: Test component interactions\n- **Mock Interfaces**: Located in `internal/infrastructure/mock/`\n- **Test Coverage**: Aim for high coverage with meaningful tests\n\n### Writing Tests\n\nWhen adding new functionality:\n\n1. **Write tests first** (TDD approach recommended)\n2. **Use table-driven tests** for multiple scenarios\n3. **Mock external dependencies** using provided interfaces\n4. **Test error conditions** not just happy paths\n5. **Keep tests focused** and independent\n\n### Local Testing with Mock Authentication\n\nFor comprehensive integration testing using local Kubernetes cluster:\n\n1. **Deploy with Mock Authentication**:\n\n   ```bash\n   make helm-install-local\n   ```\n\n   This deploys the service with:\n   - `AUTH_SOURCE=mock` - Bypasses JWT validation\n   - `JWT_AUTH_DISABLED_MOCK_LOCAL_PRINCIPAL=test-super-admin` - Mock principal\n   - `TRANSLATOR_SOURCE=mock` - File-backed ID mappings\n\n2. **Test Individual Endpoints**:\n\n   ```bash\n   # Any Bearer token works with mock auth\n   curl -H \"Authorization: Bearer test-token\" \\\n        http://lfx-v2-mailing-list-service.lfx.svc.cluster.local:8080/groupsio/services\n   ```\n\n**⚠️ Security Warning**: Never use mock authentication in production environments.\n\n## 🚀 Deployment\n\n### Kubernetes Secret\n\nBefore deploying, create the Kubernetes secret with ITX credentials. The command below is idempotent and safe to re-run (e.g. for credential rotation):\n\n```bash\nkubectl create secret generic lfx-v2-mailing-list-service -n lfx \\\n  --from-literal=ITX_CLIENT_ID=\"\u003cvalue-from-1password\u003e\" \\\n  --from-literal=ITX_CLIENT_PRIVATE_KEY=\"\u003cvalue-from-1password\u003e\" \\\n  --from-literal=ITX_AUTH0_DOMAIN=\"\u003cvalue-from-1password\u003e\" \\\n  --from-literal=ITX_AUDIENCE=\"\u003cvalue-from-1password\u003e\" \\\n  --from-literal=ITX_BASE_URL=\"\u003cvalue-from-1password\u003e\" \\\n  --dry-run=client -o yaml | kubectl apply -f -\n```\n\n\u003e **Where to find the secret values**: Look in 1Password under the **LFX V2** vault, in the secured note titled **LFX Platform Chart Values Secrets - Local Development**.\n\n### Helm Chart\n\nThe service includes a Helm chart for Kubernetes deployment:\n\n```bash\n# Install using make (recommended)\nmake helm-install\n\n# Install with local values override using make\nmake helm-install-local\n\n# Install directly with helm\nhelm upgrade --install lfx-v2-mailing-list-service ./charts/lfx-v2-mailing-list-service \\\n  --namespace lfx \\\n  --create-namespace\n\n# Install with local values override directly\nhelm upgrade --install lfx-v2-mailing-list-service ./charts/lfx-v2-mailing-list-service \\\n  --namespace lfx \\\n  --create-namespace \\\n  --values ./charts/lfx-v2-mailing-list-service/values.local.yaml\n\n# View rendered templates\nmake helm-templates\n```\n\n### Docker\n\n```bash\n# Build Docker image\nmake docker-build\n\n# Run with Docker\ndocker run -p 8080:8080 linuxfoundation/lfx-v2-mailing-list-service:latest\n```\n\n## 📡 NATS Messaging\n\nNATS serves two roles in this service: ID translation and event publishing.\n\n### ID Translation\n\nThe service uses NATS request/reply to translate v2 UUIDs to v1 SFIDs (and vice versa) via the v1-sync-helper service:\n\n| Subject | Purpose |\n|---------|---------|\n| `lfx.lookup_v1_mapping` | Translate project/committee UIDs ↔ SFIDs |\n\nKey format sent to the v1-sync-helper:\n\n- `project.uid.\u003cuuid\u003e` — v2 UUID → v1 SFID\n- `project.sfid.\u003csfid\u003e` — v1 SFID → v2 UUID\n- `committee.uid.\u003cuuid\u003e` — v2 UUID → v1 SFID (response: `projectSFID:committeeSFID`)\n\n### Published Subjects\n\nThe service publishes messages to the following NATS subjects (primarily via the v1→v2 data stream processor):\n\n| Subject | Purpose | Message Schema |\n|---------|---------|----------------|\n| `lfx.index.groupsio_service` | GroupsIO service indexing events | Indexer message with tags |\n| `lfx.index.groupsio_mailing_list` | Mailing list indexing events | Indexer message with tags |\n| `lfx.index.groupsio_member` | Member indexing events | Indexer message with tags |\n| `lfx.fga-sync.update_access` | Service and mailing list access control create/update | Generic FGA message (`update_access`) |\n| `lfx.fga-sync.delete_access` | Service and mailing list access control delete | Generic FGA message (`delete_access`) |\n| `lfx.fga-sync.member_put` | Add member to mailing list in FGA | Generic FGA message (`member_put`) |\n| `lfx.fga-sync.member_remove` | Remove member from mailing list in FGA | Generic FGA message (`member_remove`) |\n\n### Message Publisher Interface\n\nThe service uses two message types:\n\n- **Indexer Messages**: For search indexing operations (consumed by indexer services)\n- **Access Messages**: For permission management (consumed by fga-sync service)\n\n## 📖 API Documentation\n\nThe service automatically generates OpenAPI documentation:\n\n- **OpenAPI 2.0**: `gen/http/openapi.yaml`\n- **OpenAPI 3.0**: `gen/http/openapi3.yaml`\n- **JSON formats**: Also available in `gen/http/`\n\nAccess the documentation at: `http://localhost:8080/openapi.json`\n\n### Available Endpoints\n\nThe full list of available endpoints is documented via Swagger. Access the live spec at:\n\n- `http://localhost:8080/openapi.json` (JSON)\n- `http://localhost:8080/openapi3.yaml` (YAML)\n\n## 🔧 Configuration\n\nThe service can be configured via environment variables:\n\n### Core Service Configuration\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `NATS_URL` | NATS server URL | `nats://lfx-platform-nats.lfx.svc.cluster.local:4222` |\n| `NATS_TIMEOUT` | NATS connection timeout | `10s` |\n| `NATS_MAX_RECONNECT` | Maximum NATS reconnect attempts | `3` |\n| `NATS_RECONNECT_WAIT` | Wait between NATS reconnect attempts | `2s` |\n| `LOG_LEVEL` | Log level (debug, info, warn, error) | `info` |\n| `LOG_ADD_SOURCE` | Add source location to logs | `true` |\n| `PORT` | HTTP server port | `8080` |\n\n### Authentication Configuration\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `JWKS_URL` | JWKS URL for JWT verification | `http://lfx-platform-heimdall.lfx.svc.cluster.local:4457/.well-known/jwks` |\n| `JWT_AUDIENCE` | JWT token audience | `lfx-v2-mailing-list-service` |\n| `AUTH_SOURCE` | Authentication source (`jwt` or `mock`) | `jwt` |\n| `JWT_AUTH_DISABLED_MOCK_LOCAL_PRINCIPAL` | Mock principal for local dev (dev only) | `\"\"` |\n\n### ITX Proxy Configuration\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `ITX_BASE_URL` | ITX HTTP API base URL | Required |\n| `ITX_CLIENT_ID` | Auth0 client ID for M2M authentication | Required |\n| `ITX_CLIENT_PRIVATE_KEY` | RSA private key (PEM) for Auth0 JWT assertion | Required |\n| `ITX_AUTH0_DOMAIN` | Auth0 tenant domain | Required |\n| `ITX_AUDIENCE` | Auth0 audience for the ITX API | Required |\n\n\u003e **Where to find `ITX_CLIENT_ID` and `ITX_CLIENT_PRIVATE_KEY`**: Look in 1Password under the **LFX V2** vault, in the secure note **LFX Platform Chart Values Secrets - Local Development**.\n\n### ID Translator Configuration\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `TRANSLATOR_SOURCE` | Translator backend (`nats` or `mock`) | `nats` |\n| `TRANSLATOR_MAPPINGS_FILE` | YAML file for mock translator mappings | `translator_mappings.yaml` |\n\n### Development Environment Variables\n\nFor local development with mock backends (no real ITX or NATS required):\n\n```bash\nexport AUTH_SOURCE=\"mock\"\nexport JWT_AUTH_DISABLED_MOCK_LOCAL_PRINCIPAL=\"test-admin\"\nexport TRANSLATOR_SOURCE=\"mock\"\nexport TRANSLATOR_MAPPINGS_FILE=\"translator_mappings.yaml\"\nexport LOG_LEVEL=\"debug\"\n```\n\nFor local development with real NATS but mock auth:\n\n```bash\nexport NATS_URL=\"nats://localhost:4222\"\nexport AUTH_SOURCE=\"mock\"\nexport JWT_AUTH_DISABLED_MOCK_LOCAL_PRINCIPAL=\"test-admin\"\nexport TRANSLATOR_SOURCE=\"nats\"\nexport ITX_BASE_URL=\"https://api.dev.itx.linuxfoundation.org\"\nexport ITX_CLIENT_ID=\"your-client-id\"\nexport ITX_CLIENT_PRIVATE_KEY=\"$(cat tmp/local.private.key)\"\nexport ITX_AUTH0_DOMAIN=\"linuxfoundation-dev.auth0.com\"\nexport ITX_AUDIENCE=\"https://api.dev.itx.linuxfoundation.org/\"\nexport LOG_LEVEL=\"debug\"\n```\n\n## 📄 License\n\nCopyright The Linux Foundation and each contributor to LFX.\n\nSPDX-License-Identifier: MIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinuxfoundation%2Flfx-v2-mailing-list-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flinuxfoundation%2Flfx-v2-mailing-list-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinuxfoundation%2Flfx-v2-mailing-list-service/lists"}