Skip to content
Open
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
84 changes: 84 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,90 @@ The handler identity is retained in the local terminal-status cache for reportin
after a service restart. Legacy cache entries without a handler identity are
ignored with a warning rather than reported under an assumed handler name.

## Error clarification

RunCommand V2 reports classified failures using the Azure extension platform's
`ErrorWithClarification`. Positive clarification codes indicate customer input,
permissions, connectivity, policy, or VM problems. Negative codes indicate handler
or Azure infrastructure failures. Clarification codes are separate from script
exit codes and handler process exit codes.

Output-blob creation or replacement failures return exit code `-108`
(`ExitCode_OutputBlobCreateOrReplaceFailed`); error-blob creation or replacement
failures return `-109` (`ExitCode_ErrorBlobCreateOrReplaceFailed`). Once blobs
are created, periodic and final appends are best effort: failures do not change
the command result or exit code. Only the first append failure per command is
logged and written as an extension error event, across both output and error
blobs. Subsequent appends are still attempted.

Managed and immediate status reports include a `substatus` entry with
`name: "ErrorClarification"`, `status: "error"`, and the numeric `code`. The
existing instance-view message, output, script exit code, and
`treatFailureAsDeploymentFailure` behavior are preserved. A failed script can
therefore have a successful top-level deployment status and still carry its
error clarification.

Immediate commands retain the script's exit code and full terminal instance view.
An execution result already reported to the observer is not replaced by a fallback
status. If terminal reporting fails, the fallback retries the original instance
view and top-level status. Script failures carry the positive
`CommandExecution_failureExitCode` clarification, not a system-error code.

Codes are declared centrally as named `ErrorClarificationCode` constants in
[errorclarificationcodes.go](pkg/errorutil/errorclarificationcodes.go), grouped
into system and user errors like CustomScript. Shared classifications use
CustomScript's constant names and numeric values; additional RunCommand failure
sites have distinct constants to preserve source-location uniqueness.

Each code is allocated to exactly one production classification site and must
not be reused or renumbered. Higher layers add context without replacing a code
from a lower layer. The shared [error helper](pkg/errorutil/errors.go) preserves
both pointer and value platform errors, wrapped causes, and joined errors. Tests
check constant-value uniqueness, named usage at every classification site, test
references or unreachable-path explanations, and CustomScript compatibility.

The allocation ranges are:

| Absolute code range | Area |
| --- | --- |
| CustomScript values | Shared execution, input, download, identity, policy, and OS classifications |
| 1000-1999 | Download, blob/URL parsing, and preprocessing |
| 2000-2999 | Handler settings and extension policy |
| 3000-4999 | Lifecycle support, services, machine operations, and communication |
| 5000-5099 | Execution and RunAs |
| 5100-5199 | Instance-view serialization |
| 5200-5299 | Local and immediate status |
| 5300-5399 | Command processing |
| 5400-5499 | Command orchestration, upgrades, and output blobs |

Error-path tests inject filesystem, process, identity, and HTTP failures instead
of depending on the host configuration or Azure endpoints. Defensive paths that
cannot fail with the current concrete types are documented by code in the tests.
Tests expecting a production error must assert its exact named clarification code,
not only that an error occurred or that its message matches. Propagation tests
must verify the original lower-level code. Control-flow sentinels are explicitly
tested as unclassified rather than treated as failures.
Tests expecting a failed execution in status must also check the serialized
`ErrorClarification` substatus and its exact code, including when
`treatFailureAsDeploymentFailure` leaves the top-level status successful.

### Running tests on Windows

The handler runtime and full integration suite require Linux. Mocked clarification
tests can also run natively on Windows, including from VS Code:

```powershell
go test .\cmd\main -run TestCommandLineClarifications
```

Cleanup uses shared Go filesystem helpers on Linux and Windows; its error-path
tests inject filesystem failures. Only OS-specific primitives such as Linux
process-group signaling have separate implementations. The Windows signaling
default explicitly returns an unsupported-operation error; tests inject mocks.
Immediate-status tests that exercise persistence use a separate `t.TempDir()`
and `t.Setenv()` extension path per test, so existing local status files cannot
affect their results.

## Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a
Expand Down
28 changes: 28 additions & 0 deletions cmd/main/clarification_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
package main

import (
"testing"

"github.com/Azure/run-command-handler-linux/pkg/errorutil"
"github.com/stretchr/testify/require"
)

func TestCommandLineClarifications(t *testing.T) {
for _, tc := range []struct {
args []string
code int
}{
{nil, errorutil.CustomerInput_invalidCommandLineArguments},
{[]string{"handler"}, errorutil.CustomerInput_invalidCommandLineArguments},
{[]string{"handler", "enable", "extra"}, errorutil.CustomerInput_invalidCommandLineArguments},
{[]string{"handler", "invalid"}, errorutil.CustomerInput_unknownCommandLineOperation},
} {
_, err := parseCommand(tc.args)
code, ok := errorutil.FindClarification(err)
require.True(t, ok)
require.Equal(t, tc.code, code)
}
command, err := parseCommand([]string{"handler", "enable"})
require.NoError(t, err)
require.NotEmpty(t, command.Name)
}
25 changes: 16 additions & 9 deletions cmd/main/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import (
commands "github.com/Azure/run-command-handler-linux/internal/cmds"
"github.com/Azure/run-command-handler-linux/internal/commandProcessor"
"github.com/Azure/run-command-handler-linux/internal/types"
"github.com/Azure/run-command-handler-linux/pkg/errorutil"
"github.com/Azure/run-command-handler-linux/pkg/versionutil"
)

Expand All @@ -33,25 +34,31 @@ func main() {
}
}

// parseCmd looks at os.Args and parses the subcommand. If it is invalid,
// it prints the usage string and an error message and exits with code 0.
// parseCmd parses the subcommand. If it is invalid, it prints the usage string
// and a clarified error message and exits with code 2.
func parseCmd(args []string) types.Cmd {
if len(os.Args) != 2 {
cmd, err := parseCommand(args)
if err != nil {
printUsage(args)
fmt.Println("Incorrect usage.")
fmt.Println(err)
os.Exit(2)
}
op := os.Args[1]
return cmd
}

func parseCommand(args []string) (types.Cmd, error) {
if len(args) != 2 {
return types.Cmd{}, errorutil.EnsureClarification(errorutil.CustomerInput_invalidCommandLineArguments, fmt.Errorf("Incorrect usage."))
}
op := args[1]
cmd, ok := commands.Cmds[op]

// If no command was found, then exit
if !ok {
printUsage(args)
fmt.Printf("Incorrect command: %q\n", op)
os.Exit(2)
return types.Cmd{}, errorutil.EnsureClarification(errorutil.CustomerInput_unknownCommandLineOperation, fmt.Errorf("Incorrect command: %q", op))
}

return cmd
return cmd, nil
}

// printUsage prints the help string and version of the program to stdout with a
Expand Down
87 changes: 87 additions & 0 deletions internal/cleanup/clarification_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
package cleanup

import (
"errors"
"io"
"testing"

"github.com/Azure/run-command-handler-linux/internal/types"
"github.com/Azure/run-command-handler-linux/pkg/errorutil"
"github.com/go-kit/kit/log"
"github.com/stretchr/testify/require"
)

type cleanupErrorLogger struct{ err error }

type cleanupDirectory struct{}

func (cleanupDirectory) Close() error { return nil }

func (l *cleanupErrorLogger) Log(values ...interface{}) error {
for _, value := range values {
if err, ok := value.(error); ok {
l.err = err
}
}
return nil
}

func TestCleanupClarifications(t *testing.T) {
oldClear, oldDelete, oldOpen := clearExceptMostRecent, deleteDirectoriesExcept, openDownloadDirectory
t.Cleanup(func() {
clearExceptMostRecent, deleteDirectoriesExcept, openDownloadDirectory = oldClear, oldDelete, oldOpen
})
cause := errors.New("machine failure")
for _, want := range []int{errorutil.Os_FailedToCleanOldScriptsAndSettings, errorutil.Os_FailedToOpenDownloadDirectory, errorutil.Os_FailedToCleanOldRunAsDirectories} {
clearExceptMostRecent = func(*log.Context, string, string, string, uint64, string, string) error {
if want == errorutil.Os_FailedToCleanOldScriptsAndSettings {
return cause
}
return nil
}
deleteDirectoriesExcept = func(*log.Context, string, string) error { return cause }
openDownloadDirectory = func(string) (io.Closer, error) {
if want == errorutil.Os_FailedToOpenDownloadDirectory {
return nil, cause
}
return cleanupDirectory{}, nil
}
logger := &cleanupErrorLogger{}
user := ""
if want == errorutil.Os_FailedToCleanOldRunAsDirectories {
user = "test"
}
RunCommandCleanup(log.NewContext(logger), types.RCMetadata{DownloadPath: "."}, types.HandlerEnvironment{}, user)
code, ok := errorutil.FindClarification(logger.err)
require.True(t, ok)
require.Equal(t, want, code)
require.ErrorIs(t, logger.err, cause)
}
}

func TestCleanupPreservesLowerClarification(t *testing.T) {
oldClear, oldDelete, oldOpen := clearExceptMostRecent, deleteDirectoriesExcept, openDownloadDirectory
t.Cleanup(func() {
clearExceptMostRecent, deleteDirectoriesExcept, openDownloadDirectory = oldClear, oldDelete, oldOpen
})
cause := errors.New("directory read failed")
classified := errorutil.EnsureClarification(errorutil.Os_FailedToReadCleanupParentDirectory, cause)
openDownloadDirectory = func(string) (io.Closer, error) { return cleanupDirectory{}, nil }
for _, user := range []string{"", "test"} {
t.Run("runAsUser="+user, func(t *testing.T) {
clearExceptMostRecent = func(*log.Context, string, string, string, uint64, string, string) error {
if user == "" {
return classified
}
return nil
}
deleteDirectoriesExcept = func(*log.Context, string, string) error { return classified }
logger := &cleanupErrorLogger{}
RunCommandCleanup(log.NewContext(logger), types.RCMetadata{DownloadPath: "."}, types.HandlerEnvironment{}, user)
code, ok := errorutil.FindClarification(logger.err)
require.True(t, ok)
require.Equal(t, errorutil.Os_FailedToReadCleanupParentDirectory, code)
require.ErrorIs(t, logger.err, cause)
})
}
}
24 changes: 17 additions & 7 deletions internal/cleanup/cleanup.go
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,24 @@ package cleanup

import (
"fmt"
"io"
"os"
"path/filepath"
"strconv"

"github.com/Azure/azure-extension-platform/pkg/utils"
"github.com/Azure/run-command-handler-linux/internal/constants"
"github.com/Azure/run-command-handler-linux/internal/types"
"github.com/Azure/run-command-handler-linux/pkg/errorutil"
"github.com/Azure/run-command-handler-linux/pkg/linuxutils"
"github.com/go-kit/kit/log"
)

var (
openDownloadDirectory = func(name string) (io.Closer, error) { return os.Open(name) }
Comment thread
jscalev marked this conversation as resolved.
Resolved
clearExceptMostRecent = linuxutils.TryClearExtensionScriptsDirectoriesAndSettingsFilesExceptMostRecent
deleteDirectoriesExcept = linuxutils.TryDeleteDirectoriesExcept
)

func ImmediateRunCommandCleanup(ctx *log.Context, metadata types.RCMetadata, h types.HandlerEnvironment, runAsUser string) {
deleteAllScriptsAndSettings(ctx, metadata, h, runAsUser)
}
Expand All @@ -35,7 +42,7 @@ func deleteAllScriptsAndSettings(ctx *log.Context, metadata types.RCMetadata, h
ctx.Log("message", "removing all files from the download 'runas' directory "+runAsDownloadParent)
err = linuxutils.TryDeleteDirectories(ctx, runAsDownloadParent)
if err != nil {
ctx.Log("event", "could not clear runas script")
ctx.Log("event", "could not clear runas script", "error", err)
}
}
}
Expand All @@ -45,13 +52,16 @@ func deleteScriptsAndSettingsExceptMostRecent(ctx *log.Context, metadata types.R
runtimeSettingsLastSeqNumFormat := metadata.ExtName + ".%d.settings"

// check if directory exists
_, err := os.Open(metadata.DownloadPath)
dir, err := openDownloadDirectory(metadata.DownloadPath)
if err == nil {
err := utils.TryClearExtensionScriptsDirectoriesAndSettingsFilesExceptMostRecent(metadata.DownloadPath, h.HandlerEnvironment.ConfigFolder, "",
dir.Close()
err := clearExceptMostRecent(ctx, metadata.DownloadPath, h.HandlerEnvironment.ConfigFolder, "",
uint64(metadata.SeqNum), runtimeSettingsRegexFormat, runtimeSettingsLastSeqNumFormat)
if err != nil {
ctx.Log("event", "could not clear settings and script files", "error", err)
ctx.Log("event", "could not clear settings and script files", "error", errorutil.EnsureClarification(errorutil.Os_FailedToCleanOldScriptsAndSettings, err))
}
} else if !os.IsNotExist(err) {
ctx.Log("event", "could not open download directory", "error", errorutil.EnsureClarification(errorutil.Os_FailedToOpenDownloadDirectory, err))
} else {
ctx.Log("message", "directory does not exist. Skipping cleanup")
}
Expand All @@ -60,9 +70,9 @@ func deleteScriptsAndSettingsExceptMostRecent(ctx *log.Context, metadata types.R
runAsDownloadParent := filepath.Join(fmt.Sprintf(constants.RunAsDir, runAsUser), metadata.DownloadDir)
seqNumString := strconv.Itoa(metadata.SeqNum)
ctx.Log("message", "removing all files from the download 'runas' directory "+runAsDownloadParent)
err = utils.TryDeleteDirectoriesExcept(runAsDownloadParent, seqNumString)
err = deleteDirectoriesExcept(ctx, runAsDownloadParent, seqNumString)
if err != nil {
ctx.Log("event", "could not clear runas script")
ctx.Log("event", "could not clear runas script", "error", errorutil.EnsureClarification(errorutil.Os_FailedToCleanOldRunAsDirectories, err))
}
}
}
Loading
Loading