Skip to content

feat: add a new config-based API#2715

Merged
imobachgs merged 160 commits intoapi-v2from
agama-new-api
Oct 3, 2025
Merged

feat: add a new config-based API#2715
imobachgs merged 160 commits intoapi-v2from
agama-new-api

Conversation

@imobachgs
Copy link
Copy Markdown
Contributor

@imobachgs imobachgs commented Sep 9, 2025

This pull request introduces two big changes:

  • The implementation of the new HTTP API for the l10n module. Bear in mind that the specification is still a work in progress.
  • The new architecture for Agama services. The l10n module has been heavily reorganized to:
    • support the new API.
    • make it easier to maintain in the future.

The new HTTP API

Here is a brief explanation of how the new API should look like. For further details, check the ongoing description.

In general, it is designed around 3 main concepts:

  • system: represents the current status of the running system. It is not only about the configuration, but it can offer additional information (e.g., the list of supported languages, products, hardware information, etc.).
  • config: represents the user configuration for the target system.
  • proposal: represents what is going to happen during installation.

Here is the API summary (check whether we have done some changes):

GET             /system
GET             /extended_config
GET             /extended_config/{scope}
GET PUT PATCH   /config
GET PUT PATCH   /config/{scope}
GET POST PATCH  /questions
GET             /proposal
GET             /state
GET             /issues
POST            /action

This new design allows us to drastically reduce the complexity and the amount of code needed by the old API.

Of course, we still need to extend it to support more use cases (software, DASD, progress, etc.) but this one is a step in the direction we want to take.

The new architecture

Coming from a set of separate single-thread D-Bus services, we had have time to identify a few limitations that we would like to overcome in this redesign. Given that we expect several process to collaborate (holding configuration, listening for system changes, etc.) we want to implement something similar to an very simplified actor model.

With this idea in mind, each Agama module (localization, software, etc.) will live in their own package (e.g., agama-l10n, agama-software, etc.) implementing the corresponding actors/services. agama-utils contains a module with some utilities to implement this pattern.

agama-new-architecture

Actors implementation

We started using the enum-based approach described in Actors in Tokio (really great). However, after some discussion, we decided to go with a trait-based approach. See the actors module for further information.

teclator and others added 30 commits September 3, 2025 16:59
Co-authored-by: José Iván López González <jlopez@suse.com>
By adding a new query for the system endpoint and consuming data from
there.

Previous "system" query has been moved to "hostname", which most
probably will dissapear once hostname is ported to the new API and, most
probably, served as part of the system.
Read the FIXME in the code to know more.
Apart from fixing some wrong keys after a backend update.
- Some code is commented in the supervisor until l10n is able to
  dispatch the required actions (e.g., apply config).
* Replace the current implementation of the "run" function.
@coveralls
Copy link
Copy Markdown

Coverage Status

coverage: 63.649% (+0.05%) from 63.601%
when pulling 7540489 on agama-new-api
into 963a290 on api-v2.

@coveralls
Copy link
Copy Markdown

coveralls commented Oct 3, 2025

Coverage Status

coverage: 63.618% (+0.02%) from 63.601%
when pulling f64ad28 on agama-new-api
into 963a290 on api-v2.

@imobachgs imobachgs marked this pull request as ready for review October 3, 2025 12:24
Copy link
Copy Markdown
Contributor

@joseivanlopez joseivanlopez left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@imobachgs imobachgs merged commit 9cc8b2d into api-v2 Oct 3, 2025
15 of 16 checks passed
@imobachgs imobachgs deleted the agama-new-api branch October 3, 2025 12:27
@imobachgs imobachgs mentioned this pull request Oct 3, 2025
imobachgs added a commit that referenced this pull request Oct 6, 2025
Update the changes files according to the changes introduced in #2715.
teclator added a commit that referenced this pull request Nov 11, 2025
## Problem

There is a new config based HTTP API and all the services needs to be
adapted. The aim of this PR is to adapt the network backend service
(replace #2840).

- #2715

## Solution

In the new architecture all the Agama modules will live in its own
package implementing the actors/service as described in
(#2715), but as network was
already using a actors model using an enums approach it was decided to
use the current service in the first iteration of changes.

### Changes done

- Added the actions for getting the system, proposal and current network
configuration using the actual actions passing messages system based on
enums.
- All the structs or types that are related to the API (needs to be
serialized) has been moved to agama-utils, it was decided to not depend
on agama-lib anymore. The types will be re-exported to be used by
agama-network when needed.
- As the current merge is concatenating the connections array, the patch
**(updateConfig)** will replace the connections with the given one when
present, but is something we need to revisit and decide how to do it in
a better way.
- Removed the network web service.
- As the proposal, system info and config contains similar collections
and just change the absence or presence of some of them we have
introduced the **NetworkCollection** and
**NetworkConnectionCollections** in order to do the conversion between
them.

### TODO

- Move to the actors/service model using traits instead of enums and
adding the issues and progress monitor to the network service.
- Remove all the actions which are not needed anymore (old network web
service).
- Add unit tests covering the new approach.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants