Skip to content

feat(client): export the HTTP client, add the run client and resolve the profile by endpoint - #33

Open
grubmeshi wants to merge 10 commits into
mainfrom
feature/single-go-bin-runner
Open

grubmeshi wants to merge 10 commits into
mainfrom
feature/single-go-bin-runner

Conversation

@grubmeshi

@grubmeshi grubmeshi commented Oct 13, 2026 •

Copy link
Copy Markdown
Collaborator

The building block runner (meshcloud/building-block-runner#86) and the Terraform provider (meshcloud/terraform-provider-meshstack#392) use the CLI as a Go module. This PR gives them one generic client for every meshObject kind, a run client for runners, and a profile resolution that works without a stored profile. It removes more lines than it adds (about +5,050/-6,440).

Commits

  1. Profile resolution. The profile is picked by name (--profile, MESHSTACK_PROFILE), else the current profile when it has the endpoint in use, else the only stored profile with that endpoint. An unknown name is an error, also for meshstack logout -p. Without a matching profile, the CLI runs with the endpoint and credential from the settings and stores nothing. Only meshstack login creates a profile. An endpoint is a scheme, a host and an optional port; one with a path, query or user info is refused. With a full URL, meshstack api and meshstack api-docs take its scheme and host as the endpoint. A token that an earlier version cached is gone, so users log in with --apitoken again, and that token is sent until it really expires.
  2. internal/http moves to client/http. This commit only renames, so that other modules can use the HTTP client and its options.
  3. One generic client. Every kind uses client.MeshObjectClient[M, Filter] with string ids, whose List returns an iterator. Actions of an object follow the links of its _links through hal.Links, and the commands that trigger, approve, reject or abort a run or read its logs use these links too. The per-kind wrappers and client.Raw are gone. A GET or DELETE is retried on every transient failure, any other method on 423, 429 and 503, so meshstack api -X DELETE retries a 502 and 504 like a GET. A 423 on the Terraform state goes straight to tofu, which names the lock holder and waits itself. meshstack api-docs reads the API docs the endpoint serves at /api/openapi, without a login, and keeps them until the ETag changes; the published docs are the fallback.
  4. Runner types as one enum.
  5. Run client. Claim, RegisterSource, UpdateSourceSteps, DownloadArtifact and UploadArtifact. All but Claim address a run by its uuid, because the API key of a runner cannot read a run.
  6. http.Error.IsTemporary() is true for 408, 423, 429 and every 5xx, so that a caller that polls knows when to go on.
  7. Go 1.27.4 toolchain, because Go 1.27.0 has GO-2026-6859 in net/http.
  8. Retry on a refused connection for every method, with a warning on each retry, for up to about six minutes (1, 2, 4, 8, 16 s, then every 30 s). A client then outlasts a start or restart of meshStack. A command against a wrong endpoint waits too; the warning says why, and Ctrl-C stops it.
  9. Redaction in --debug logs. Secrets in request and response bodies are redacted by JSON pointer: plaintext and clientSecret anywhere, the OIDC tokens and codes, the access token of an API key login and the run token of a claim. A caller adds pointers with http.WithRedactedJsonPointers. The Authorization header stays redacted.
  10. Error bodies. http.Error shows the body as it came and reads it with BodyAsJson[T](); client.MeshObjectErrorOf turns it into a client.MeshObjectError and keeps what wraps it. meshstack api prints nothing on stdout for an answer outside 2xx; the error shows what meshStack answered, or the body as it came where it is no error of meshStack.

Review focus

The largest parts are the profile resolution (internal/profile/resolve.go) and the generic client (client/meshobject.go, client/types/hal). Commit 2 only renames.

Cross-repo PRs and merge order

#86 and #392 pin the current head of this PR in go.mod, so each push here needs a new pin in both.

  1. This PR, then a CLI release. feat: wait for a run already going, and name the building blocks a failed run waits on #86 moves its go.mod pin from this head to that release.
  2. feat!: run every building block runner type in one Go binary building-block-runner#86
  3. fix: follow the client API of the meshStack CLI terraform-provider-meshstack#392, whose meshstack-cli Pin check stays red until this PR is merged.
  4. meshcloud/meshfed-release#11468
  5. feat(meshstack/run-controller): deploy a building block runner into a Kubernetes tenant meshstack-hub#401

🤖 Generated with Claude Code

@meshcloud-gh-actions

meshcloud-gh-actions Bot commented Oct 13, 2026 •

Copy link
Copy Markdown

Coverage of the acceptance run against the meshStack backend, on 75703bd34853f000047e48119cec29ac7978c506.

Scope Coverage
Unit tests 79.4%
Acceptance tests 57.6%
Combined 82.0%
Uncovered functions
client/api_key.go:18: MeshApiKey.meshObjectId 0.0%
client/api_key_permissions.go:20: ApiKeyPermissions.AllCodes 0.0%
client/api_key_permissions.go:33: ApiKeyPermissions.WorkspaceCodes 0.0%
client/api_key_permissions.go:263: AllApiKeyPermissions 0.0%
client/api_key_permissions.go:267: WorkspacePermissionCodes 0.0%
client/binding_status.go:18: *MeshGroupBindingStatus.WaitsForApproval 0.0%
client/binding_status.go:22: *MeshUserBindingStatus.WaitsForApproval 0.0%
client/building_block_definition.go:68: MeshBuildingBlockDefinitionApprovalPolicies.NothingRequiresApproval 0.0%
client/building_block_definition.go:79: DisabledSchedule 0.0%
client/building_block_definition.go:86: MeshBuildingBlockDefinitionSchedule.IsDisabled 0.0%
client/building_block_definition.go:90: MeshBuildingBlockDefinitionSpec.HasNeutralPolicies 0.0%
client/building_block_definition.go:94: MeshBuildingBlockDefinitionSpec.WithNeutralPolicies 0.0%
client/building_block_definition.go:148: MeshBuildingBlockDefinition.meshObjectId 0.0%
client/building_block_definition_version.go:98: MeshBuildingBlockType.TagInputTargets 0.0%
client/building_block_definition_version.go:219: MeshBuildingBlockDefinitionVersion.meshObjectId 0.0%
client/building_block_definition_version.go:222: MeshBuildingBlockDefinitionVersion.meshObjectNoSortQuery 0.0%
client/building_block_run.go:138: meshBuildingBlockRunClient.Claim 0.0%
client/building_block_run.go:158: MeshBuildingBlockRun.meshObjectId 0.0%
client/building_block_run_source.go:64: meshBuildingBlockRunClient.RegisterSource 0.0%
client/building_block_run_source.go:73: meshBuildingBlockRunClient.UpdateSourceSteps 0.0%
client/building_block_run_source.go:78: meshBuildingBlockRunClient.DownloadArtifact 0.0%
client/building_block_run_source.go:87: meshBuildingBlockRunClient.UploadArtifact 0.0%
client/building_block_run_source.go:98: *cappedWriter.Write 0.0%
client/building_block_runner.go:67: MeshBuildingBlockRunner.meshObjectId 0.0%
client/building_block_v2.go:236: *MeshBuildingBlockV2.IsWaitingForInput 0.0%
... and 66 more

covdata func names a method without its receiver, so an entry can belong to an implementation nothing selects rather than to a function the tests never reached. Open the file and line before reading one as a coverage gap.

@grubmeshi
grubmeshi force-pushed the feature/single-go-bin-runner branch from f7111e1 to 73db1b9 Compare October 13, 2026 13:52
@grubmeshi grubmeshi changed the title feat(client): publish the HTTP layer as client/http, with Basic auth feat: basic auth credential and the runner API in client Oct 13, 2026
@grubmeshi
grubmeshi force-pushed the feature/single-go-bin-runner branch from 73db1b9 to ebf91ce Compare October 13, 2026 13:58
@grubmeshi
grubmeshi force-pushed the feature/single-go-bin-runner branch 2 times, most recently from 9ab69a7 to 322b873 Compare October 15, 2026 19:18
@grubmeshi
grubmeshi force-pushed the feature/single-go-bin-runner branch 10 times, most recently from 3a034bf to eb512e3 Compare October 23, 2026 11:53
@grubmeshi grubmeshi changed the title feat: basic auth credential and the runner API in client feat: basic auth, client/http and the runner API in client Oct 23, 2026
@grubmeshi
grubmeshi force-pushed the feature/single-go-bin-runner branch 2 times, most recently from 5975d78 to 98854c7 Compare October 28, 2026 11:58
@grubmeshi
grubmeshi force-pushed the feature/single-go-bin-runner branch 3 times, most recently from abbd309 to e90226d Compare October 29, 2026 04:56
@grubmeshi grubmeshi changed the title feat: basic auth, client/http and the runner API in client feat(client): add the runner API and export the HTTP client as client/http Oct 29, 2026
@grubmeshi
grubmeshi force-pushed the feature/single-go-bin-runner branch 2 times, most recently from c85b993 to 0332c2c Compare October 30, 2026 09:04
@grubmeshi
grubmeshi force-pushed the feature/single-go-bin-runner branch from 2ac56de to 3926fcc Compare November 2, 2026 11:36
@grubmeshi
grubmeshi force-pushed the feature/single-go-bin-runner branch from 3926fcc to 8e92887 Compare November 11, 2026 23:13
Comment thread docs/demo/fakemeshstack/server.go Fixed
@grubmeshi
grubmeshi force-pushed the feature/single-go-bin-runner branch from 8e92887 to 9807a76 Compare November 12, 2026 00:14
@grubmeshi
grubmeshi force-pushed the feature/single-go-bin-runner branch 2 times, most recently from 2d49f9d to 9f1ecad Compare November 12, 2026 02:53
@grubmeshi grubmeshi changed the title feat(client): add the runner API and export the HTTP client as client/http feat(client): export the HTTP client, add the run client and resolve the profile by endpoint Nov 12, 2026
@grubmeshi
grubmeshi marked this pull request as ready for review November 12, 2026 03:41
@grubmeshi
grubmeshi force-pushed the feature/single-go-bin-runner branch 6 times, most recently from 3032cd0 to f74c926 Compare November 13, 2026 08:18
grubmeshi and others added 2 commits November 19, 2026 09:14
…un without a stored one

A command takes the profile that --profile or MESHSTACK_PROFILE names, and an unknown name is an
error. Without a name it takes the current profile when no endpoint is given or the profile has
that endpoint, else the only stored profile with that endpoint. With no such profile it runs with
the endpoint and the credential from the settings alone: it stores nothing and caches no token.
Only 'meshstack login' creates a profile.

An endpoint is a scheme and a host, and one with a path is refused. 'meshstack api <URL>' takes
the origin of the URL as the endpoint.

A profile stores an API token with its other credentials. A token that an earlier version cached
is gone, so log in with --apitoken again.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…ion to client/types/version

Another module can then name the HTTP client, its request options and the version type that
client/ already uses in its exported API. The files move unchanged, apart from import paths.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@grubmeshi
grubmeshi force-pushed the feature/single-go-bin-runner branch from f74c926 to d537434 Compare November 19, 2026 08:21
grubmeshi and others added 8 commits November 19, 2026 16:29
…Client and hal.Links

Every kind's client is client.MeshObjectClient[M, Filter] with Read, List, Create, Update and
Delete under a type alias, and List reads a page only when the caller asks for an object of it.
An action of an object follows a link of its _links through hal.Links: Get, Post and Delete send
the media type of the kind, decode the answer and let its links follow themselves too. A link to
another origin than the endpoint is refused. client.Raw and the per-kind methods such as
ReadFunc, TriggerRun and GetLogs are gone.

client/http has one DoRequest, which returns the response body, and UnmarshalJsonBody,
ReadAllBody and IgnoreResponse consume it. Request options set the retry policy, refuse
redirects and capture the response header. A GET and a DELETE are retried on every transient
failure, any other method on 423, 429 and 503. The debug log shows the first 1024 bytes of a
body as they came.

internal/json is the only importer of encoding/json/v2. The polymorph package reads and writes
a struct by its type property, as the implementation of a definition version needs. The API docs
are cached by the ETag of /api/openapi.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
MeshBuildingBlockRunnerImplementationTypes is an enum.Enum like the other enums of the client,
and MeshBuildingBlockRunnerSpec.ImplementationType is an entry of it.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…hrough the run client

A building block runner works with client.Client.BuildingBlockRun: Claim hands it the next run
with the run token, the inputs and the implementation, and sends the version of the HTTP
client's user agent as X-Meshcloud-Runner-Version. RegisterSource, UpdateSourceSteps,
DownloadArtifact and UploadArtifact address a run by its uuid, because the API key of a runner
may not read a run. The names follow the operations of the meshObject API.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
http.Error.IsTemporary is true for 408, 423, 429 and every 5xx, so that a caller that polls, as
a runner does for a pipeline run, knows when to go on.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Go 1.27.0 has GO-2026-6859 in net/http, which fails the vulnerability check.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A refused connection is retried under every policy and for every method, because the server received
nothing. A runner started together with meshStack then waits for its API, and a client outlasts a
restart of meshStack. Each retry logs a warning, so a person who gave a wrong endpoint sees why the
command waits and can stop it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
… JSON pointer

A debug log shows a JSON body indented, with the value at each redacted JSON pointer replaced by
"[REDACTED]", and applies one-token pointers to the fields of a url-encoded form. Every request
redacts the plaintext of a secret and the clientSecret of an API key; http.WithRedactedJsonPointers
adds the tokens of an OIDC grant, the access token of an API key login and the run token of a
claimed run.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…client/http

http.Error now shows the body as it came, and BodyAsJson reads it into the type the caller
expects. client.MeshObjectError reads the error body of meshStack and keeps what wraps the
http.Error, such as the authorization of a 403. internal/oidc reads its OAuth error itself.

meshstack api no longer writes the body of a failed answer to stdout; the error says what
meshStack answered.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@grubmeshi
grubmeshi force-pushed the feature/single-go-bin-runner branch from d537434 to 75703bd Compare November 19, 2026 15:29
@sonarqubecloud

Copy link
Copy Markdown

@grubmeshi
grubmeshi requested a review from j0g3sc November 19, 2026 15:41
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.

2 participants