app

package
v0.19.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 21, 2026 License: Apache-2.0 Imports: 64 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	CONTAINERFILE = "Containerfile"
	DOCKERFILE    = "Dockerfile"
)
View Source 
const (
	DEFAULT_FILE_LIMIT = 10_000
	MAX_FILE_LIMIT     = 100_000

	// FS_FILE_ACCESS_SETTING carries the allowed directory list into the fs
	// module's settings; the compiled-in registration injects it from the
	// app config (app_config.fs.file_access)
	FS_FILE_ACCESS_SETTING = "file_access"
)
View Source 
const (
	VOL_PREFIX_SECRET = "cl_secret:"
)

Variables

View Source 
var (
	CONTENT_TYPE_JSON = []string{"application/json"}
	CONTENT_TYPE_TEXT = []string{"text/plain"}
	CONTENT_TYPE_HTML = []string{"text/html; charset=utf-8"}

	SERVER_NAME = []string{"OpenRun"}
	// Boosted requests (HX-Request + HX-Boosted) get the full page while
	// non-boosted HTMX requests get the partial block, so both headers are
	// part of the cache key
	VARY_HEADER_VALUE = []string{"HX-Request", "HX-Boosted"}
)

Functions

func AddUserFile 

func AddUserFile(ctx context.Context, file *types.UserFile) error

func AppFileOptions added in v0.15.2 

func AppFileOptions() *syntax.FileOptions

func ClearCleanup 

func ClearCleanup(thread *starlark.Thread, key string)

ClearCleanup clears a defer function from the thread local

func ClearCleanupModule added in v0.19.0 

func ClearCleanupModule(thread *starlark.Thread, modulePath, key string)

ClearCleanupModule clears a defer entry registered under the given module path. Cleanup code can run when TL_CURRENT_MODULE_FULL_PATH points at a different plugin — a result cursor is often iterated after calls to other plugins — so code clearing an entry outside the owning module's own call must name the module explicitly or the wrong plugin's map is searched, leaving the entry registered and failing the request as a resource leak

func DeferCleanup 

func DeferCleanup(thread *starlark.Thread, key string, deferFunc apptype.DeferFunc, strict bool)

DeferCleanup defers a close function to call when the API handler is done

func DeferCleanupModule added in v0.19.0 

func DeferCleanupModule(thread *starlark.Thread, modulePath, key string, deferFunc apptype.DeferFunc, strict bool)

DeferCleanupModule is DeferCleanup with the owning module path passed explicitly instead of read from TL_CURRENT_MODULE_FULL_PATH. Use it when the entry may be registered outside the owning module's own call

func DeleteUserFile 

func DeleteUserFile(ctx context.Context, id string) error

func DescribeExternalProviderManifest added in v0.19.0 

func DescribeExternalProviderManifest(ctx context.Context, execPath, sha256Hex string) (string, []string, string, error)

DescribeExternalProviderManifest launches a plugin provider executable briefly and returns its version, the served module names, and the module manifest serialized as JSON. The manifest can be persisted (it is stored in the provider database row at install time) and later registered with RegisterExternalProviderManifest without launching the provider again.

func GetContext 

func GetContext(thread *starlark.Thread) context.Context

func GetExternalProviderInfo added in v0.19.0 

func GetExternalProviderInfo(name string) (string, []string, bool)

GetExternalProviderInfo returns a registered provider's executable path and served module paths (e.g. "store.ex"), for tests and diagnostics.

func GetUserFile 

func GetUserFile(ctx context.Context, id string) (*types.UserFile, error)

func InitFileStore 

func InitFileStore(connectString string) error

func NewFSModule added in v0.19.0 

func NewFSModule() sdk.Module

func RegisterEmbeddedProviders added in v0.19.0 

func RegisterEmbeddedProviders()

RegisterEmbeddedProviders registers every provider added to the SDK's embedded registry (plugin.RegisterEmbedded, used by custom OpenRun builds that compile plugins in). Called once at server startup.

func RegisterExternalProvider added in v0.19.0 

func RegisterExternalProvider(name, execPath, sha256Hex string) error

RegisterExternalProvider launches the provider executable briefly to Describe its modules and registers them for loading as "<module>.ex". A provider registered under the same name is replaced; a module served by a different provider is a conflict.

func RegisterExternalProviderManifest added in v0.19.0 

func RegisterExternalProviderManifest(name, execPath, sha256Hex, manifestJson string) error

RegisterExternalProviderManifest registers a plugin provider from a previously captured manifest (see DescribeExternalProviderManifest), without launching the provider executable. This is the database-backed install path: replicas register modules from the stored manifest, and the provider process is only launched when an app calls one of its modules.

func RegisterLocalProvider added in v0.19.0 

func RegisterLocalProvider(name string, config *sdk.ServeConfig, options LocalProviderOptions)

RegisterLocalProvider registers an SDK plugin provider config to be served in-process. Modules are loadable as "<module>.in". Re-registering the same provider name replaces it (server initialization can run more than once in a test process); a module served by a different provider panics, so a conflicting build fails at startup, not on a user request.

func SystemPluginsAllowed added in v0.18.7 

func SystemPluginsAllowed(serverConfig *types.ServerConfig, userId string) bool

SystemPluginsAllowed reports whether userId may invoke the privileged system plugins (openrun_admin, build): an authenticated (non-anonymous) caller, or any caller when security.unsafe_allow_system_plugins_anon is set. Shared by the pluginHook gate and the openrun plugin's system_plugins_allowed report, so the two cannot drift

func UnregisterExternalProvider added in v0.19.0 

func UnregisterExternalProvider(name string)

UnregisterExternalProvider removes a provider and its modules from the registry. Running per-app provider processes are not affected; they are torn down with their apps.

func UnregisterLocalProvider added in v0.19.0 

func UnregisterLocalProvider(name string)

UnregisterLocalProvider removes a provider and its modules from the registry. For tests.

Types

type AccessType 

type AccessType string
const (
	UserAccess AccessType = "user"
	AppAccess  AccessType = "app"
)

type App 

type App struct {
	*types.Logger
	*types.AppEntry
	Name         string
	CustomLayout bool

	// App config that takes default values from toml config, overridden with app level metadata.
	// It is important that this property is used instead of reading from app metadata config, so that toml
	// config defaults are applied.
	AppConfig types.AppConfig

	AppRunPath string // path to the app run directory
	// contains filtered or unexported fields
}

App is the main object that represents a OpenRun app. It is created when the app is loaded

func NewApp 

func NewApp(sourceFS *appfs.SourceFs, workFS *appfs.WorkFs, logger *types.Logger,
	appEntry *types.AppEntry, systemConfig *types.SystemConfig,
	plugins map[string]types.PluginSettings, appConfig types.AppConfig, notifyClose chan<- types.AppPathDomain,
	secretEvalFunc func([][]string, string, string) (string, error),
	auditInsert func(*types.AuditEvent) error, serverConfig *types.ServerConfig,
	rbacApi rbac.RBACAPI, bindings []*types.Binding) (*App, error)

func (*App) ActiveContainerName added in v0.17.3 

func (a *App) ActiveContainerName() (container.ContainerName, bool)

ActiveContainerName returns the container from the last successful app reload.

func (*App) Audit 

func (a *App) Audit() (*types.ApproveResult, error)

func (*App) Close 

func (a *App) Close() error

func (*App) ExecuteContainerBuild added in v0.18.4 

func (a *App) ExecuteContainerBuild(ctx context.Context, plan *BuildPlan) error

ExecuteContainerBuild builds the image described by the plan returned from PrepareContainerBuild. It touches no DB state, so no transaction is needed.

func (*App) Initialize 

func (a *App) Initialize(ctx context.Context, dryRun types.DryRun) error

func (*App) LitestreamSidecarName added in v0.18.15 

func (a *App) LitestreamSidecarName() (container.ContainerName, bool)

LitestreamSidecarName returns the app's litestream replication sidecar container name when one applies (docker/podman with a litestream-enabled sqlite binding), so the stale container cleanup treats it as active.

func (*App) MaterializeSource added in v0.18.7 

func (a *App) MaterializeSource() (string, error)

MaterializeSource writes the app's current source files to a new temp directory (delegating to the source FS; supported for non-dev apps whose source is in the metadata file store). The caller owns the directory

func (*App) PauseIdleShutdown added in v0.18.15 

func (a *App) PauseIdleShutdown()

PauseIdleShutdown suspends idle-based container shutdown for this app's container handler, if it has one. See ContainerHandler.PauseIdleShutdown

func (*App) PrepareContainerBuild added in v0.18.4 

func (a *App) PrepareContainerBuild(ctx context.Context) (*BuildPlan, error)

PrepareContainerBuild computes the build plan for the app's container image: image name, whether a build is needed, and (when it is) a temp source dir extracted from the app's source FS. All DB reads happen here, so the caller can close the transaction backing the source FS before ExecuteContainerBuild. Returns nil for apps with no image to build (no container, image-spec, dev).

func (*App) Reload 

func (a *App) Reload(ctx context.Context, force, immediate bool, dryRun types.DryRun, opts ReloadOptions) (bool, error)

func (*App) ResetFS 

func (a *App) ResetFS()

func (*App) ResumeIdleShutdown added in v0.18.15 

func (a *App) ResumeIdleShutdown()

ResumeIdleShutdown re-enables idle-based container shutdown for this app

func (*App) ServeHTTP 

func (a *App) ServeHTTP(w http.ResponseWriter, r *http.Request)

type AppPlugins 

type AppPlugins struct {
	sync.Mutex
	// contains filtered or unexported fields
}

func NewAppPlugins 

func NewAppPlugins(app *App, pluginConfig map[string]types.PluginSettings, appAccounts []types.AccountLink) *AppPlugins

func (*AppPlugins) GetPluginSettings added in v0.19.0 

func (p *AppPlugins) GetPluginSettings(pluginPath, accountName string) types.PluginSettings

GetPluginSettings resolves the plugin settings for a plugin path and account, applying the same app account-link resolution as GetPlugin. Used for external plugin providers, whose instances live in the provider process instead of the AppPlugins instance cache.

type BuildPlan added in v0.18.4 

type BuildPlan struct {
	ImageName  container.ImageName
	SourceDir  string // temp source dir, already extracted; set only when NeedsBuild
	NeedsBuild bool
}

BuildPlan captures the state needed to build an app image after the DB transaction backing the app's source FS has been closed. PrepareBuild does all source reads (image identity hash and temp source dir extraction); ExecuteBuild only runs the container build and touches no DB state.

type ByteWindow added in v0.15.5 

type ByteWindow struct {
	// contains filtered or unexported fields
}

func NewByteWindow added in v0.15.5 

func NewByteWindow(windowSeconds int, attrs ...attribute.KeyValue) *ByteWindow

func (*ByteWindow) Totals added in v0.15.5 

func (bw *ByteWindow) Totals() (sent, recv uint64)

type ContainerHandler added in v0.15.20 

type ContainerHandler struct {
	*types.Logger

	GenImageName container.ImageName // generated image name
	// contains filtered or unexported fields
}

func NewContainerHandler added in v0.15.20 

func NewContainerHandler(logger *types.Logger, app *App, containerFile string,
	serverConfig *types.ServerConfig, configPort int32, lifetime, scheme, health, buildDir string, sourceFS appfs.ReadableFS,
	paramMap map[string]string, containerConfig types.Container, stripAppPath bool,
	containerVolumes []string, secretsAllowed [][]string, cargs map[string]any, bindings []*types.Binding,
	devSettings *types.DevSettings) (*ContainerHandler, error)

func (*ContainerHandler) ActiveContainerName added in v0.17.3 

func (h *ContainerHandler) ActiveContainerName() (container.ContainerName, bool)

ActiveContainerName returns the last container this handler successfully started or reused.

func (*ContainerHandler) Close added in v0.15.20 

func (h *ContainerHandler) Close() error

func (*ContainerHandler) DevReload added in v0.15.20 

func (h *ContainerHandler) DevReload(ctx context.Context, dryRun bool) error

func (*ContainerHandler) ExecuteBuild added in v0.18.4 

func (h *ContainerHandler) ExecuteBuild(ctx context.Context, plan *BuildPlan) error

ExecuteBuild builds the image described by a plan from PrepareBuild. It reads only from the plan's temp source dir, never the DB, so callers can (and should) close their DB transaction before invoking it.

func (*ContainerHandler) GetHealthUrl added in v0.15.20 

func (h *ContainerHandler) GetHealthUrl(appHealthUrl string) string

func (*ContainerHandler) GetProxyUrl added in v0.15.20 

func (h *ContainerHandler) GetProxyUrl() string

func (*ContainerHandler) IsImageSpec added in v0.17.3 

func (h *ContainerHandler) IsImageSpec() bool

IsImageSpec reports whether this container handler was configured with an upstream image reference (i.e. `--spec image` / `container.source = "image:..."`). Such apps need ProdReload to run on every admin reload so that RefreshImage can resolve the current digest and recreate the container when the upstream tag has moved; build-spec apps only need ProdReload on Initialize since their image identity is captured by the source-content hash.

func (*ContainerHandler) LitestreamSidecarName added in v0.18.15 

func (h *ContainerHandler) LitestreamSidecarName() (container.ContainerName, bool)

LitestreamSidecarName returns the app's litestream sidecar container name when replication is enabled (docker/podman only), for active-container tracking so the stale container cleanup loop does not stop it.

func (*ContainerHandler) PauseIdleShutdown added in v0.18.15 

func (h *ContainerHandler) PauseIdleShutdown()

PauseIdleShutdown suspends idle-based container shutdown for this app. See idlePaused. Blocks until any idle shutdown already committed past its final pause recheck has finished: the idle runner holds stateLock from that recheck through the container stop, so acquiring it here joins an in-progress stop instead of returning while the container is still being stopped concurrently (the caller proceeds with a restart handoff on return). Any iteration that has not yet taken stateLock observes the flag at the recheck

func (*ContainerHandler) PrepareBuild added in v0.18.4 

func (h *ContainerHandler) PrepareBuild(ctx context.Context) (*BuildPlan, error)

PrepareBuild mirrors the image-build portion of ProdReload without any container side effects. The image name is content-hashed, so a later ProdReload for the same source finds the built image via its ImageExists check and skips the build. Returns nil for apps with no image to build (dev apps build through DevReload, image-spec apps pull rather than build).

func (*ContainerHandler) ProdReload added in v0.15.20 

func (h *ContainerHandler) ProdReload(ctx context.Context, dryRun bool, verify bool) error

ProdReload reloads the prod container. verify indicates the caller wants the update to be verified and rollback-capable; for in-place managers this makes a snapshot failure fatal (we refuse to mutate the live Deployment when we cannot capture the state needed to roll it back), rather than proceeding with an irreversible update.

func (*ContainerHandler) ResumeIdleShutdown added in v0.18.15 

func (h *ContainerHandler) ResumeIdleShutdown()

ResumeIdleShutdown re-enables idle-based container shutdown for this app

func (*ContainerHandler) Run added in v0.15.20 

func (h *ContainerHandler) Run(ctx context.Context, path string, cmdArgs []string, env []string) (*exec.Cmd, error)

func (*ContainerHandler) WaitForHealth added in v0.15.20 

func (h *ContainerHandler) WaitForHealth(attempts int, containerName container.ContainerName, expectHash string) error

type ContainerState 

type ContainerState string
const (
	ContainerStateUnknown       ContainerState = "unknown"
	ContainerStateRunning       ContainerState = "running"
	ContainerStateIdleShutdown  ContainerState = "idle_shutdown"
	ContainerStateHealthFailure ContainerState = "health_failure"
)

type ExternalProvider added in v0.19.0 

type ExternalProvider struct {
	Name     string
	ExecPath string
	Sha256   string // hex sha256 of the executable, "" skips verification (dev)
	Version  string
	// contains filtered or unexported fields
}

ExternalProvider is one registered plugin provider executable and the modules it serves.

type FileInfo 

type FileInfo struct {
	Name  string
	Size  int64
	IsDir bool
	Mode  int
}

type LocalProvider added in v0.19.0 

type LocalProvider struct {
	Name    string
	Config  *sdk.ServeConfig
	Options LocalProviderOptions
	// contains filtered or unexported fields
}

LocalProvider is one registered in-process plugin provider and the modules it serves.

type LocalProviderOptions added in v0.19.0 

type LocalProviderOptions struct {
	// SystemModules lists modules whose functions require an authenticated
	// caller (RegisterSystemPlugin semantics), e.g. exec, openrun_admin.
	SystemModules []string

	// SettingsHook, if set, can augment a module's settings with app-derived
	// config before the module instance is initialized (e.g. the fs module's
	// allowed directory list comes from the app config, not plugin settings).
	// It must return a new map if it adds entries; the input map may be nil.
	SettingsHook func(a *App, module string, settings map[string]any) map[string]any
}

LocalProviderOptions carries host-side policy for an in-process provider's modules, beyond what the transport-neutral ServeConfig expresses.

type PluginResponse 

type PluginResponse struct {
	// contains filtered or unexported fields
}

PluginResponse is a starlark.Value that represents the response to a plugin request

func NewErrorCodeResponse 

func NewErrorCodeResponse(errorCode int, err error, value any) *PluginResponse

func NewErrorCodeResponseThread added in v0.19.0 

func NewErrorCodeResponseThread(errorCode int, err error, value any, thread *starlark.Thread) *PluginResponse

NewErrorCodeResponseThread is NewErrorCodeResponse with the thread attached, so an explicit error check by the app (accessing .error or truth-testing the response) clears the thread-local failure state, the way NewErrorResponse does. Without the thread, a handled coded error would still fail the next plugin call or the handler return.

func NewErrorResponse 

func NewErrorResponse(err error, thread *starlark.Thread) *PluginResponse

func NewResponse 

func NewResponse(value any) *PluginResponse

func NewStreamResponse 

func NewStreamResponse(value any) *PluginResponse

func (*PluginResponse) Attr 

func (r *PluginResponse) Attr(name string) (starlark.Value, error)

func (*PluginResponse) AttrNames 

func (r *PluginResponse) AttrNames() []string

func (*PluginResponse) Freeze 

func (r *PluginResponse) Freeze()

func (*PluginResponse) Hash 

func (r *PluginResponse) Hash() (uint32, error)

func (*PluginResponse) String 

func (r *PluginResponse) String() string

func (*PluginResponse) Truth 

func (r *PluginResponse) Truth() starlark.Bool

func (*PluginResponse) Type 

func (r *PluginResponse) Type() string

func (*PluginResponse) UnmarshalStarlarkType 

func (r *PluginResponse) UnmarshalStarlarkType() (any, error)

type ReloadOptions added in v0.18.3 

type ReloadOptions struct {
	// ReloadContainer, when true, (re)loads the prod container (rebuild/restart
	// as needed). It is true for reload and initialize operations; only the
	// metadata-only paths leave it false. Image-spec apps always reload.
	ReloadContainer bool
	// Verify indicates the caller wants a verified, rollback-capable update.
	// For in-place container managers (Kubernetes) this makes a missing
	// rollback snapshot a fatal error rather than proceeding with an
	// irreversible in-place update.
	Verify bool
	// SkipContainer skips the prod container reload entirely, including for
	// image-spec apps (which ReloadContainer=false alone does not skip). Used
	// by the image pre-build pass, which needs the app fully configured but
	// must not touch containers.
	SkipContainer bool
}

ReloadOptions controls how App.Reload handles the prod container.

type SSEMessage 

type SSEMessage struct {
	// contains filtered or unexported fields
}

type StarlarkFunction 

type StarlarkFunction func(thread *starlark.Thread, fn *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error)

type Tracker added in v0.15.5 

type Tracker struct {
	// contains filtered or unexported fields
}

Tracker is a reverse proxy with byte count tracking

func NewTracker added in v0.15.5 

func NewTracker(proxy *httputil.ReverseProxy, windowSeconds int, attrs ...attribute.KeyValue) *Tracker

func (*Tracker) GetRollingTotals added in v0.15.5 

func (t *Tracker) GetRollingTotals() (sent, recv uint64)

Accessor to read the rolling totals.

func (*Tracker) ServeHTTP added in v0.15.5 

func (t *Tracker) ServeHTTP(w http.ResponseWriter, r *http.Request)

Source Files

View all Source files

Directories

Path Synopsis
The store plugin module, implemented against the plugin SDK (pkg/plugin).
 The store plugin module, implemented against the plugin SDK (pkg/plugin).
storeprovider command
Command storeprovider is the out-of-process provider build of the store plugin: the same module implementation that is compiled into OpenRun as "store.in" (internal/app/store), served as an external provider.
 Command storeprovider is the out-of-process provider build of the store plugin: the same module implementation that is compiled into OpenRun as "store.in" (internal/app/store), served as an external provider.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.