Friendly Tech. FCC Service

Introduction

ft-fcc-service runs FCC/USAC broadband-compliance speed and latency diagnostic campaigns over a CPE fleet. A campaign (a test) describes a fleet of devices, a schedule, and success thresholds; each concrete execution of a test is a activation. A test with reactivation configured produces one activation per day for the configured number of days, each carrying its own snapshot of the settings that were in force when it ran — see The fcc_activation Settings Snapshot.

The service computes and stores the pass/fail verdict for every measurement; the ACS only ever reports raw numbers. See The Pass/Fail Formula for the one formula both sides use, and for what "both sides" actually means.

Its Place Among Three Repositories

FCC diagnostics is split across three independently deployed repositories, connected by two narrow contracts and nothing else:

Repository Role Talks to ft-fcc-service via

ft-acs module fcc-core

Runs the actual diagnostic against the CPE fleet (TR-181 DownloadDiagnostics / UploadDiagnostics, WAN usage sampling) and reports raw measurements.

Hazelcast queues only — see The Governing Decision.

ft-fcc-service (this service)

Owns the campaign lifecycle, the pass/fail verdict, the ftfcc schema, and the FCC result tables in ClickHouse.

 — 

ui-backend

Authenticates the portal user and proxies iot-webservice/iotw/FCC/ to /FCC/ one to one, injecting the identity headers.

Inbound REST, described in REST API.

The ACS and ft-fcc-service do not know each other: no SOAP client, no REST call, no address of one in the configuration of the other, in either direction. See The Governing Decision for why, and what it costs.

External Dependencies — Exactly Five

ft-fcc-service has exactly five external dependencies. There is no sixth.

Dependency Role

Hazelcast (client)

The only channel to the ACS: five queues carry commands, acks, results, device states and activation events. See Hazelcast Queues.

ftfcc schema

Own schema, read-write, owned and migrated by this service (Liquibase). See ftfcc Schema.

ClickHouse ftacs_qoe_ui_data

Shared with QoE monitoring (diag_speed_test, diag_ip_ping already live there). This service owns the fcc_result_speed / fcc_result_latency tables and a dedicated Flyway history. See ClickHouse Schema.

ftacs

Read-only DataSource, dedicated database account with SELECT grants on a fixed table list. See Startup Behaviour.

iotw (optional)

Read-only DataSource over two tables of ui-backend’s schema, for the saved conditions a campaign configuration can name. Lazy: an installation that does not grant it starts normally and refuses only `sourceType=Condition. See The iotw Grant.

Inbound REST from ui-backend only

No other caller is trusted; there is no authentication of its own. See No Authentication by Design.

Milestone Status

Milestone Status Scope

M0

Implemented

Project skeleton: two DataSources, Liquibase on ftfcc, Flyway on ClickHouse with a dedicated history table, the Hazelcast client, the DTO package (wire contract 1.5 — see What Contract 1.3 Changed, What Contract 1.4 Changed and What Contract 1.5 Changed), actuator health.

M1

Implemented

fcc_test / _config / _setting_speed / _device / _activation / _acs_outbox tables; PUT /FCC/item/details, POST /FCC/item/details, POST /FCC/items, POST /FCC/activate; the transactional outbox, dispatcher, ack-timeout poller, ack/result listeners and the pass/fail calculator (com.friendly.fcc.orchestration, listener, clickhouse, calc) — the full activation-through-result path is implemented and code-read. See Endpoints Implemented in M1 and Messaging.

M2

Implemented

The two lifecycle state machines (com.friendly.fcc.statemachine, The State Machine as the Single Decision Point); the fccDeviceStateQueue / fccActivationEventQueue listeners with the atomic fcc_device_state upsert and the STOPPING drain recount; the SCHEDULED / PLANNED pollers and the stop-grace / finish-grace watchdog; daily reactivation that skips missed slots; the LATENCY test type with fcc_test_setting_latency and ClickHouse fcc_result_latency; the after-stop window and fcc_result_dead_letter; POST /FCC/stop, POST /FCC/pause, DELETE /FCC/items, POST /FCC/devices/status, POST /FCC/activate (whose mode DEV-1381 later dropped — a campaign with a date is booked and one without starts now, decided from the campaign and not from the request), POST /FCC/admin/result-dead-letter/resend; and the fcc_audit trail. See Endpoints Implemented in M2.

M3

Implemented

The three wizard reads against the read-only ACS schema — POST /FCC/manufacturerAndModelByTestType (FccCatalogService / FtacsCatalogDao / FccTierPresets) and POST /FCC/devices/resolve / POST /FCC/devices/count, each serving both JSON and a multipart serial upload on one URL (FccDeviceResolveService, FtacsDeviceResolveDao, FccSerialListParser, FccDomainScopeResolver, FccCpeProtocolEnum); the two administration tables fcc_model_capability and fcc_domain_setting with four endpoints each on FccAdminController; the save-time three-level settings resolution chain; POST /FCC/item/clone (removed in the DEV-1381 reconciliation — export then import replaces it); a device selection on PUT /FCC/item/details; fcc_test_device.protocol; the connection-range, capability-ceiling, diagnostic-URL and positive-value validators; and FccAuditActionEnum.CLONE with the two new fcc_audit entity types. See Endpoints Implemented in M3, Device Resolution and The Settings Resolution Chain.

M4

Implemented

Two halves. Reporting: POST /FCC/reports/list / results / generate / export, the streamed XLSX/CSV extract, the three-state ClickHouse DEGRADED gate, and the report read path over the two result tables — see Endpoints Implemented in M4 and The Report Read Path. Legacy ETL: ftacs.ug_fcc_speed_result / ug_fcc_latency_result replayed into ClickHouse under reconstructed anchors, runs and iterations, driven by POST /FCC/admin/legacy-import/{start,status,stop} and cursored by the thirteenth ftfcc table — see Legacy FCC Import and fcc_legacy_import.

M5

Implemented

XML configuration import/export (PUT /FCC/item/export / /item/import, com.friendly.fcc.configio) — see Configuration Import and Export and Endpoints Implemented in M5; the Helm chart at helm/ft-fcc-service/ — see Deployment; the queue-depth, queue-age, outbox-row, outbox-age, command-ack-latency, result-buffer-depth and Hazelcast-connectivity Prometheus meters (FccMetricsSampler, FccAckMetrics) — see Metrics; and this documentation module’s ongoing maintenance.

Every package of this service is implemented and code-read as of this pass:

  • statemachine — FccTestStateMachine, FccActivationStateMachine and their event, effect, transition and context types; pure functions, no Spring.

  • orchestration — outbox dispatcher, ack-timeout poller, FccStalledActivationService, FccStopCommandPublisher, FccActivationScheduler / FccActivationSchedulingService, FccActivationWatchdog / FccActivationClosingService, FccReactivationService.

  • listener — one take() thread per queue for all four inbound queues (fccCommandAck, fccResultQueue, fccDeviceStateQueue, fccActivationEventQueue), driven by FccQueueListenerRunner.

  • service — FccTestService, FccActivationService, FccActivationHandler, FccAckService, FccResultIngestService, FccActivationEventService, FccDeviceStateService, FccActivationTransitionService, FccStopService, FccTestLifecycleService, FccTestDeleteHandler, FccDeviceStatusService, FccResultDeadLetterService, FccAuditService, and the M3 additions FccCatalogService, FccDeviceResolveService, FccSerialListParser, FccDomainScopeResolver / FccDomainScope, FccDomainSettingResolver, FccModelCapabilityProvider, FccModelCapabilityAdminService, FccDomainSettingAdminService (FccTestCloneService was here too, and went with POST /FCC/item/clone).

  • calc — FccSpeedStatusCalculator and FccLatencyStatusCalculator, the two halves of the one pass/fail formula.

  • clickhouse — FccResultSpeedDao, FccResultLatencyDao and the batched writer.

  • repository — FccOutboxDao, FccActivationDao, FccTestDao, FccDeviceStateDao, FccResultDeadLetterDao and their MySQL/Oracle statement pairs.

  • configio — M5. FccConfigExportService / FccConfigImportService, FccConfigXmlWriter / FccConfigXmlReader, FccConfigRecordFields (the reflection-derived XML vocabulary), FccConfigXmlNames.

  • metrics — M5. FccMetricsSampler (the queue/outbox/Hazelcast-connectivity gauges), FccAckMetrics (command ack latency).

  • mapper, web.controller, web.dto, identity, config, domain, health, runtime.

Nothing in this documentation is marked TBD any more. M0 through M5 are all implemented and described from the shipped code, as the table above states; nothing in this service remains genuinely unbuilt except the one reserved, unused endpoint named under Reserved, Not Used in v1.

Who Should Read What

Role Start here

Operator standing up or troubleshooting the service

Operations — configuration, health semantics, startup checks, troubleshooting table.

Backend developer changing the REST surface or validators

REST API — identity contract, endpoint reference, validation rules.

Backend developer changing the ACS integration

Messaging — queue contract, outbox, DTO rules, the pass/fail formula.

Anyone touching the schema

Database — table-by-table reference, the settings resolution chain, and the design rules behind both.

Backend developer changing how a fleet is selected

Device Resolution — the ACS columns this service reads, the closed condition set, the SQL rules, and how a selection is frozen.

Anyone importing, or reading a report over, pre-existing FCC measurements

Legacy FCC Import — what the ETL reconstructs, what it deliberately does not recompute, and why an imported row can look different from a live one. The operator’s sequence is The Legacy Import Runbook.

Anyone moving a campaign’s configuration between installations

Configuration Import and Export — the XML element vocabulary, what it deliberately does not carry, and the domain and legacy-anchor rules an implementer would otherwise have to guess.

Anyone wiring a Prometheus scrape or an alert rule against this service

Metrics — the complete rendered meter table, where NaN appears and what it means, and the Prometheus naming trap this service’s own counter names fall into.

Anyone deploying or operating the Kubernetes chart

Deployment — the image, the Helm chart’s load-bearing defaults, and why liveness and readiness are split. The chart’s own helm/ft-fcc-service/README.md carries the full values reference.

Frontend developer

docs/openapi/ft-fcc-service.yaml — the generated OpenAPI snapshot, which is the contract document for /FCC/**. Read it alongside REST API, which carries the reasoning the schema cannot.

Anyone new to the system

Architecture — the governing decision and what it costs.