Fix: validate automation config keys

[BelhsanHmida]

Description

• A mistake in a data generator's config was reported against parameters, for forecast and report automations alike, sending the caller looking for a mistake in a part of the request that was fine. The create endpoint wrapped every ValidationError from the service as {"parameters": ...}, discarding which schema had failed.
• A scheduling automation accepted config and data-generator with 201 Created and silently ignored both. It now refuses each by name with a 422: a schedule automation's scheduler, and the flex config it runs under, follow from the asset and its flex context, so accepting either would record a choice that nothing goes on to read.
• A report automation without a reporter raised a bare string, naming no field. It is now reported under data-generator.
• An unsupported automation type is now reported under type.
• Added an errors_reported_for(section) context manager in flexmeasures/data/services/automations.py, which re-raises a ValidationError keyed by the section it came from, and wrapped each raise site with the section it belongs to: the window check, the forecast and report parameter loads, the forecast window resolution, the schedule trigger message and the schedule sensor resolution report against parameters; the forecaster and reporter setups report against config.
• Three error paths that reached the caller unkeyed are now keyed as parameters: the unknown-field error from AssetTriggerSchema (raised inside resolve_schedule_automation_sensors, whose docstring already promised the caller would report it against the parameters), the bare messages from validate_automation_window, and the offset and window errors from resolve_automation_window, which was evaluated as an argument and so sat outside the wrapper.
• flexmeasures add automation now reports "Invalid automation:" instead of "Invalid parameters:", since the fault is not always in the parameters, and the keyed messages now say where it is.
• The scheduling rejection lives in refuse_fields_a_schedule_automation_cannot_use, so that create_automation stays within the C901 complexity budget.

This is not a breaking change. A client parsing message.json.parameters will find config errors under message.json.config, but the automation endpoints landed in v3.0-37 and v3.0-38, both inside the unreleased v1.1.0, so no released client can be parsing this shape.

The issue predates #2297 and #2536 and is partly out of date: unknown parameters keys were already rejected with a field-specific 422, with nothing persisted. Criterion 6 is covered by a new test rather than by new code.

• Added changelog item in documentation/changelog.rst

Look & Feel

Before, a forecast automation with a bad config key:

{"message": {"json": {"parameters": {"not-a-config-field": ["Unknown field."]}}}}

After:

{"message": {"json": {"config": {"not-a-config-field": ["Unknown field."]}}}}

Before, a schedule automation sent a config and a data-generator:

201 Created

After:

{"message": {"json": {
  "config": ["A schedule automation configures no data generator of its own: its scheduler and flex config follow from the asset and its flex context."],
  "data-generator": ["A schedule automation does not choose a data generator: its scheduler follows from the asset."]
}}}

Before, a report automation with no reporter:

{"message": {"json": {"parameters": ["A reporter is required for report automations (e.g. PandasReporter)."]}}}

After:

{"message": {"json": {"data-generator": ["A reporter is required for report automations (e.g. PandasReporter)."]}}}

On the command line:

$ flexmeasures add automation --asset 1 --name "Bad forecaster config" --cron "0 6 * * *" --sensor 1 --config config.yml
Invalid forecast automation: {'config': {'not-a-config-field': ['Unknown field.']}}
Aborted!

How to test

pytest flexmeasures/api/v3_0/tests/test_automations_api.py
pytest flexmeasures/cli/tests/test_automations.py
pytest flexmeasures/data/tests/

New tests:

• test_post_automation_reports_a_config_error_against_the_config — forecasting and reporting; the error is keyed config and no parameters key is present.
• test_post_automation_reports_a_parameter_error_against_the_parameters — forecasting, reporting and scheduling; the error is keyed parameters and no config key is present.
• test_post_schedule_automation_rejects_a_data_generator_and_its_config — each field is refused by name, and nothing is persisted.
• test_post_report_automation_without_a_reporter_names_the_field_to_fill_in — keyed data-generator.
• test_a_refused_automation_leaves_nothing_behind — three failing requests leave the Automation, DataSource and AssetAuditLog row counts unchanged.
• test_add_forecast_automation_reports_a_config_error_against_the_config — the CLI equivalent.

Updated: seven CLI tests asserted the old wording, "Invalid parameters", which contradicts itself once the messages can name the config instead. They now assert the new wording and the key the message is reported under.

Each new test was proven to fail before it was called done:

What was broken	What went red
The endpoint re-wraps as {"parameters": e.messages} again	the two config tests, the two schedule-rejection tests and the reporter-less test
errors_reported_for("parameters") renamed to "mislabelled"	all three parameter tests, including the scheduling one
The CLI string put back to "Invalid <noun> parameters"	all eight CLI tests
An audit record written before validation, and committed on the way out of the 422	test_a_refused_automation_leaves_nothing_behind

Each break was restored and the suite re-run.

Full suites, run one at a time: flexmeasures/api/v3_0/tests/ 518 passed; flexmeasures/cli/tests/ 234 passed, 1 xfailed; flexmeasures/data/tests/ 389 passed.

Further Improvements

Merge order: #2554 should merge first. Main's "New automation" form shows the Data generator and Config fields for every automation type; #2554 gates them so that a schedule automation sends neither. Without that gating, this PR's new rejection turns leftover text in a hidden field into a 422 as soon as the user picks scheduling.

The API changelog section here is numbered against #2554's v3.0-38. If this PR lands first, renumber it to v3.0-38.

Related Items

Closes #2498.

---

Sign-off

• I agree to contribute to the project under Apache 2 License.
• To the best of my knowledge, the proposed patch is not based on code under GPL or other license that is incompatible with FlexMeasures

[read-the-docs-community]

Documentation build overview

📚 flexmeasures | 🛠️ Build #34748001 | 📁 Comparing c7d5a1c against latest (4f45c65)

  🔍 Preview build  

32 files changed · + 6 added · ± 23 modified · - 3 deleted

+ Added

• _autosummary/flexmeasures.api.ui.html
• _autosummary/flexmeasures.api.ui.sensors.html
• _autosummary/flexmeasures.api.ui.session.html
• _autosummary/flexmeasures.data.models.registry.html
• _autosummary/flexmeasures.utils.bound_utils.html
• api/ui.html

± Modified

• changelog.html
• genindex.html
• http-routingtable.html
• py-modindex.html
• _autosummary/flexmeasures.api.html
• _autosummary/flexmeasures.api.v3_0.assets.html
• _autosummary/flexmeasures.api.v3_0.html
• _autosummary/flexmeasures.data.models.html
• _autosummary/flexmeasures.data.models.time_series.html
• _autosummary/flexmeasures.data.schemas.sensors.html
• and 13 more...

- Deleted

• _autosummary/flexmeasures.api.dev.html
• _autosummary/flexmeasures.api.dev.sensors.html
• api/dev.html

[BelhsanHmida]

Tested this locally,

Each automation type now names the part of the request at fault. A bad key in a forecaster's or a reporter's config comes back under config, where it used to come back under parameters. A bad parameter key, a negative duration and a window given as all three of start-offset, end-offset and duration all come back under parameters, the last two of which used to arrive with no field named at all. A report automation that names no reporter comes back under data-generator rather than as a bare string.

A schedule automation refuses a config and a data-generator by name, singly and together, where it used to answer 201 Created and quietly ignore both. Sending neither still creates the automation, so the ordinary path is untouched; with #2554 in, the form gates both fields by type and never sends either for a schedule.

The CLI reports the same keys, and --data-generator --type scheduling is still caught by the usage check before the service sees it.

Permissions still come first: a bad config on an asset I may not write to answers 403, with nothing in the response about the asset. And a refusal leaves nothing behind the automation, data source and audit log counts are unchanged across the failing requests.

[Flix6x]

I only request to keep changelog verbosity at bay.