Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 61 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -164,3 +164,64 @@ EBUILD_TARGETS=http://local-mirror:8080/gitweb.cgi?p=EdgeTX/cloudbuild.git;a=blo
# This is the default refresh interval in seconds
EBUILD_TARGETS_REFRESH_INTERVAL=300
```

## Limiting targets and flag values to releases

Some radios, options and option values only exist in some EdgeTX releases.
In `targets.json` they can be limited with
[semver constraints](https://github.com/Masterminds/semver#checking-version-constraints),
checked against each release's version (`sem_ver` if set, e.g. `nightly`):

| Field | On | Limits |
|---|---|---|
| `version_supported` | a target | the target |
| `version_supported` | a flag | the whole flag, i.e. every value in that definition |
| `values_version_supported` | a flag | individual values, as a map from value to constraint |

```json
"targets": {
"newradio": { "description": "Example New Radio", "version_supported": ">= 3.0.0-0" }
},
"flags": {
"power_led_blue": {
"build_flag": "POWER_LED_BLUE",
"values": ["YES", "NO"],
"version_supported": "< 3.0.0-0"
}
},
"tags": {
"colorlcd": {
"flags": {
"language": {
"values": ["AR", "CN"],
"values_version_supported": { "AR": ">= 3.0.0-0" }
}
}
}
}
```

- A flag's `version_supported` and `values_version_supported` can be
combined: a value is supported only if both allow the release. Keys of
`values_version_supported` must be listed in `values`.
- Flags are defined globally and per tag. A constraint only applies to the
definition it's in, so a flag defined in several places is limited in
each.
- Build requests that use an unsupported target, flag or value for the
requested release are rejected.
- The API exposes the result per release as `exclude_targets` and
`exclude_flags`, so clients can hide what a release can't build. A flag
with all its values excluded is dropped by clients.

**Use `-0` on the version in constraints** (`>= 3.0.0-0`, `< 3.0.0-0`)
when pre-releases should follow the same rule as releases. A constraint
without a pre-release part never matches pre-releases, so if pre-releases
are listed in `releases`:

- `>= 3.0.0` excludes `v3.0.0-rc1`; `>= 3.0.0-0` includes it.
- `< 3.0.0` also excludes `v2.12.6-rc1`; `< 3.0.0-0` includes 2.x
pre-releases and excludes 3.0 ones.

`-0` is the lowest possible pre-release, so `3.0.0-0` sits just before every
3.0 pre-release. This only matters for releases with a pre-release version:
`nightly` uses `sem_ver` (e.g. `v3.0.0`), which isn't one.
16 changes: 16 additions & 0 deletions artifactory/build_request.go
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@ var (
ErrReleaseNotSupported = errors.New("release not supported")
ErrTargetNotSupported = errors.New("target not supported")
ErrOptionFlagNotSupported = errors.New("option flag not supported")

ErrOptionFlagNotSupportedByRelease = errors.New("option flag not supported by release")
)

type OptionFlag struct {
Expand Down Expand Up @@ -43,6 +45,10 @@ func (e *BuildRequestError) Error() string {
return fmt.Sprintf("%s: %s", e.Err.Error(), e.What)
}

func (e *BuildRequestError) Unwrap() error {
return e.Err
}

func NewBuildRequest() *BuildRequest {
return &BuildRequest{
defs: targets.GetTargets(),
Expand Down Expand Up @@ -78,6 +84,16 @@ func (req *BuildRequest) Validate() error {
What: flag.String(),
}
}
ok, constraint := req.defs.IsOptionFlagSupportedByRelease(
req.Target, flag.Name, flag.Value, req.Release,
)
if !ok {
return &BuildRequestError{
Err: ErrOptionFlagNotSupportedByRelease,
What: fmt.Sprintf("%s requires release %s, got %s",
flag.String(), constraint, req.Release),
}
}
}
return nil
}
Expand Down
51 changes: 51 additions & 0 deletions artifactory/build_request_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import (
"testing"

"github.com/edgetx/cloudbuild/artifactory"
"github.com/edgetx/cloudbuild/targets"
"github.com/stretchr/testify/assert"
)

Expand Down Expand Up @@ -36,3 +37,53 @@ func TestBuildHashIsTheSameForDiffOrderFlagArrays(t *testing.T) {

assert.Equal(t, req1.HashTargetAndFlags(), req2.HashTargetAndFlags())
}

func TestValidateOptionFlagRelease(t *testing.T) {
defs, err := targets.ReadTargetsDefFromBytes([]byte(`{
"releases": {
"nightly": { "sha": "000", "sem_ver": "v3.0.0" },
"v2.12.5": { "sha": "211" }
},
"flags": {
"language": { "build_flag": "TRANSLATIONS", "values": ["EN"] },
"power_led_blue": {
"build_flag": "POWER_LED_BLUE", "values": ["YES", "NO"],
"version_supported": "< 3.0.0-0"
}
},
"tags": {
"colorlcd": { "flags": { "language": {
"values": ["AR"], "values_version_supported": { "AR": ">= 3.0.0-0" }
}}}
},
"targets": {
"tx16s": { "description": "TX16S", "tags": ["colorlcd"] },
"x7": { "description": "X7" }
}
}`), "")
assert.Nil(t, err)

prev := targets.GetTargets()
targets.SetTargets(defs)
defer targets.SetTargets(prev)

ar := []artifactory.OptionFlag{{Name: "language", Value: "AR"}}

assert.Nil(t, artifactory.NewBuildRequestWithParams("nightly", "tx16s", ar).Validate())

err = artifactory.NewBuildRequestWithParams("v2.12.5", "tx16s", ar).Validate()
assert.ErrorIs(t, err, artifactory.ErrOptionFlagNotSupportedByRelease)
assert.EqualError(t, err,
"option flag not supported by release: language=AR requires release >=3.0.0-0, got v2.12.5")

// value unknown for the target: unchanged error
err = artifactory.NewBuildRequestWithParams("nightly", "x7", ar).Validate()
assert.ErrorIs(t, err, artifactory.ErrOptionFlagNotSupported)

// whole flag limited to releases before 3.0
blue := []artifactory.OptionFlag{{Name: "power_led_blue", Value: "NO"}}
assert.Nil(t, artifactory.NewBuildRequestWithParams("v2.12.5", "x7", blue).Validate())
err = artifactory.NewBuildRequestWithParams("nightly", "x7", blue).Validate()
assert.EqualError(t, err,
"option flag not supported by release: power_led_blue=NO requires release <3.0.0-0, got nightly")
}
11 changes: 11 additions & 0 deletions doc/PublicAPI.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,17 @@
This endpoint allows for retrieving the supported targets and build options.
It returns the configured `targets.json` (see [here](../targets.json)).

Each release also includes what it can't build, computed from the
`version_supported` and `values_version_supported` constraints (see the
[README](../README.md#limiting-targets-and-flag-values-to-releases)):

- `exclude_targets`: targets not supported by this release.
- `exclude_flags`: option flag values not supported by this release, as a map
from flag name to values, e.g. `{"language": ["AR"]}`.

Both are omitted when empty. Clients should hide these for the selected
release; build requests using them are rejected.

#### CURL

```sh
Expand Down
20 changes: 15 additions & 5 deletions targets.json
Original file line number Diff line number Diff line change
Expand Up @@ -88,14 +88,17 @@
"FI",
"FR",
"IT",
"KO",
"NL",
"PL",
"PT",
"RU",
"SE",
"UA"
]
],
"values_version_supported": {
"RU": ">= 2.10.0-0",
"UA": ">= 2.10.0-0"
}
},
"fai_mode": {
"build_flag": "FAI",
Expand All @@ -107,7 +110,8 @@
},
"power_led_blue": {
"build_flag": "POWER_LED_BLUE",
"values": ["YES", "NO"]
"values": ["YES", "NO"],
"version_supported": "< 3.0.0-0"
},
"pxx1": {
"build_flag": "PXX1",
Expand Down Expand Up @@ -138,7 +142,12 @@
"colorlcd": {
"flags": {
"language": {
"values": ["AR", "CN", "HE", "JP", "SK", "TW"]
"values": ["AR", "CN", "HE", "JP", "KO", "SK", "TW"],
"values_version_supported": {
"AR": ">= 3.0.0-0",
"HE": ">= 2.9.0-0",
"KO": ">= 2.11.0-0"
}
}
}
},
Expand Down Expand Up @@ -178,7 +187,8 @@
"flags": {
"kcx_btaudio": {
"build_flag": "KCX_BTAUDIO",
"values": ["YES"]
"values": ["YES"],
"version_supported": ">= 3.0.0-0"
}
}
}
Expand Down
Loading
Loading