linglong/api/schema/v1.yaml

1073 lines
29 KiB
YAML

# SPDX-FileCopyrightText: 2023 UnionTech Software Technology Co., Ltd.
# SPDX-License-Identifier: LGPL-3.0-or-later
#
# NOTE:
# This yaml file is converted to json schema by running
# yq e '.properties = ( [
# .$defs | keys | .[] as $type | {
# "key" : $type,
# "value": {
# "$ref": "#/$defs/"+$type
# }
# } ] | from_entries
# )' -o json
# Check ../../tools/codegen.sh for details
#
# WARNING:
# Please make sure every changes in this file is backward compatible.
$schema: http://json-schema.org/draft-04/schema#
description: Types used as v1 API of linglong
D-Bus service, configuration files and CLI output.
The top level type is a place holder to make quicktype work.
$defs:
InspectResult:
description: the result of inspecting a container
type: object
properties:
appID:
type: string
description: appID of container
ApplicationConfiguration:
title: ApplicationConfiguration
description: application configuration
type: object
required:
- version
properties:
version:
type: string
description: version of configuration file
permissions:
$ref: '#/$defs/ApplicationConfigurationPermissions'
XDGDirectoryPermissions:
title: XDGDirectoryPermissions
type: array
items:
type: object
required:
- allowed
- dirType
properties:
allowed:
type: boolean
description: whether the xdg dir is allowed
dirType:
type: string
description: type of xdg dir, could be one of [Desktop, Downloads, Documents, Music, Pictures, Videos]
ApplicationConfigurationPermissions:
title: ApplicationConfigurationPermissions
description: application configuration permissions
type: object
properties:
xdgDirectories:
$ref: '#/$defs/XDGDirectoryPermissions'
binds:
type: array
items:
type: object
title: ApplicationConfigurationPermissionsBind
description: items of container
required:
- source
- destination
properties:
source:
type: string
description: source file of host
destination:
type: string
description: mount source file to the container
innerBinds:
type: array
description: inner binds of container
items:
type: object
title: ApplicationConfigurationPermissionsInnerBind
description: items of inner binds of container
required:
- source
- destination
properties:
source:
type: string
description: source file of container
destination:
type: string
description: mount source file to the another position of container
ContainerProcessStateInfo:
description: |
information about process which in container that start by ll-cli, all content
will write to /run/linglong/UID/PID
type: object
required:
- containerID
- app
- base
properties:
containerID:
type: string
app:
type: string
base:
type: string
runtime:
type: string
extensions:
type: array
description: extensions of container
items:
type: string
InteractionRequest:
description: |
structured message which inspired by freedesktop Notification Spec.
refer: https://specifications.freedesktop.org/notification-spec/latest/protocol.html#id-1.10.3.3.4
type: object
required:
- appName
- summary
- timeout
properties:
appName:
type: string
summary:
type: string
body:
type: string
actions:
type: array
items:
type: string
timeout:
type: integer
InteractionReply:
description: message from user reply
type: object
properties:
action:
description: choice which in requested actions
type: string
OCIConfigurationPatch:
title: OCIConfigurationPatch
description: oci configuration patch
type: object
required:
- ociVersion
- patch
properties:
ociVersion:
type: string
description: version of oci configuration patch
patch:
type: array
description: oci configuration patch
CLIContainer:
title: CLIContainer
description: this is the output result of ll-cli ps --json
type: object
required:
- pid
- id
- package
properties:
pid:
type: integer
description: pid of container
id:
type: string
description: id of container
package:
type: string
description: package of container
UABMetaInfo:
title: UABMetaInfo
type: object
required:
- version
- sections
- digest
- uuid
- layers
properties:
version:
description: The format version of linglong.meta data.
type: string
const: '1'
onlyApp:
description: whether this UAB file has been exported in only-App mode.
type: boolean
sections:
type: object
required:
- bundle
properties:
bundle:
description:
Name of the section contains the read only filesystem image.
It SHOULD always be 'linglong.bundle'.
type: string
icon:
description: Name of the section contains the icon of this UAB file.
It SHOULD always be 'linglong.icon'.
type: string
digest:
description: The digest of the bundle section.
type: string
uuid:
description: The version 4 uuid of this UAB file,
generated by UAB builder when this UAB file is created.
examples:
- b2f33c7b-615c-4d7d-9181-e1a22010a749
type: string
layers:
title: UABLayer
type: array
minItems: 1
items:
type: object
required:
- info
- minified
properties:
info:
$ref: '#/$defs/PackageInfoV2'
minified:
description: Whether this layer file is minified or not.
type: boolean
BuilderProject:
title: BuilderProject
description: Linglong project build file.
type: object
required:
- version
- package
- build
- base
properties:
version:
type: string
description: version of build file
exclude:
type: array
description:
exclude files during exporting UAB. Every item should be absolute path in container.
It could be a directory or a regular file.
e.g. - /usr/share/locale (exclude all files which in this directory)
- /usr/lib/libavfs.a (exclude one file)
items:
type: string
include:
type: array
description:
include files during exporting UAB. For example, the packer can declare a
file/directory (e.g. /usr/share/locale/zh_CN) in the excluded directory
(e.g. /usr/share/locale) to exclude all files in /usr/share/locale
except /usr/share/locale/zh_CN.
items:
type: string
package:
title: BuilderProjectPackage
description: package of build file
type: object
required:
- id
- kind
- name
- version
- description
properties:
id:
type: string
description: id of package
kind:
type: string
description: kind of package
name:
type: string
description: name of package
version:
type: string
description: version of package
description:
type: string
description: description of package
architecture:
type: string
description: architecture of package
channel:
type: string
description: channel of package
extension_of:
type: string
description: extension of whom
libs:
description: extra ld search path
type: array
items:
type: string
env:
description: Predefined environment variables when the extension is applied
type: object
additionalProperties:
type: string
permissions:
$ref: '#/$defs/ApplicationConfigurationPermissions'
runtime:
type: string
description: used runtime of package
base:
type: string
description: used base of package
sources:
type: array
description: sources of package
items:
title: BuilderProjectSource
description: items of sources of builder project
type: object
required:
- kind
properties:
kind:
type: string
description: kind of source
url:
type: string
description: url of source
digest:
type: string
description: digest of source
name:
type: string
description: name of source
commit:
type: string
description: commit of source
version:
type: string
description: version of source
submodules:
type: boolean
description: whether to checkout submodules
build:
title: BuilderProjectBuildScript
description: build script of builder project
type: string
buildext:
title: BuilderProjectBuildExt
description: build extension for builder project
type: object
properties:
apt:
description: build extension for apt
type: object
properties:
build_depends:
description: packages to be installed in build environment before build starting
type: array
items:
type: string
depends:
description: packages to be installed in runtime environment
type: array
items:
type: string
command:
type: array
description: command of builder project
items:
type: string
strip:
title: BuilderProjectStripScript
description: strip script of builder project
type: string
modules:
title: BuilderProjectModules
description: |
Specify how to split application into modules.
type: array
items:
title: BuilderProjectModules
description: items of modules of builder project
type: object
required:
- name
- files
properties:
name:
type: string
description: module name
files:
type: array
description: module install files
items:
type: string
description: module install file
BuilderConfig:
description: Configuration file for ll-builder.
type: object
required:
- version
- repo
properties:
version:
type: integer
description: version of builder config
offline:
type: boolean
description: use offline mode when build
arch:
type: string
description: arch of builder config
cache:
type: string
description: cache of builder config
repo:
type: string
description: repo of builder config
RepoConfig:
description: Configuration file for local linglong repository.
type: object
required:
- version
- defaultRepo
- repos
properties:
version:
type: integer
description: version of repo config
defaultRepo:
type: string
description: default repo of repo config
repos:
type: object
description: repos of repo config
additionalProperties:
type: string
description: additional properties of repos
RepoConfigV2:
description: Configuration file for local linglong repository.
type: object
required:
- version
- defaultRepo
- repos
properties:
version:
type: integer
description: version of repo config
defaultRepo:
type: string
description: default repo of repo config
repos:
type: array
description: repos of repo config
items:
$ref: '#/$defs/Repo'
minItems: 1
Repo:
description: Configuration for a single repository.
type: object
required:
- name
- url
- priority
properties:
name:
type: string
description: repo name
url:
type: string
description: repo url
alias:
type: string
description: alias of repo name
priority:
type: integer
description: priority of repo
mirror_enabled:
type: boolean
description: whether mirror is enabled for this repo
LayerInfo:
description: Meta information on the head of layer file.
type: object
required:
- version
- info
properties:
version:
type: string
description: version of layer info
info: true
PackageManager1Package:
title: PackageManager1Package
description: package manager of linglong
type: object
required:
- id
properties:
channel:
type: string
description: channel of package manager
id:
type: string
description: id of package manager
version:
type: string
description: version of package manager
module:
type: string
description: module of package manager
PackageInfoDisplay:
title: PackageInfoDisplay
description: this is the each item output of ll-cli list --json
allOf:
- $ref: '#/$defs/PackageInfoV2'
- type: object
requested:
- info
properties:
install_time:
type: integer
description: package install time
PackageInfoV2:
title: PackageInfoV2
description: this is the each item output of ll-cli list --json
type: object
required:
- channel
- id
- schema_version
- module
- arch
- version
- kind
- name
- size
- base
properties:
uuid:
type: string
description: this property is only used for app which instead from UAB
and it should be null in other conditions.
channel:
type: string
description: channel of package info
id:
type: string
description: id of package info
schema_version:
type: string
description: version of 'PackageInfo'
module:
type: string
description: module of package info
arch:
type: array
description: arch of package info
items:
type: string
version:
type: string
description: version of package info
kind:
type: string
description: kind of package info
name:
type: string
description: name of package info
size:
description: Uncompressed package size in bytes
type: integer
runtime:
type: string
description: runtime of package info
base:
type: string
description: base of package info
command:
type: array
description: command of package info
items:
type: string
permissions:
$ref: '#/$defs/ApplicationConfigurationPermissions'
description:
type: string
description: description of package info
compatible_version:
type: string
description: record linyaps package is compatible with linyaps component version
extensions:
type: array
description: description of extension
items:
$ref: '#/$defs/ExtensionDefine'
ext_impl:
$ref: '#/$defs/ExtensionImpl'
PackageInfo:
title: PackageInfo
description: this is the each item output of ll-cli list --json
type: object
required:
- appid
- module
- arch
- version
- kind
- name
- size
- base
properties:
channel:
type: string
description: channel of package info
appid:
type: string
description: appid of package info (deprecated in V2)
module:
type: string
description: module of package info
arch:
type: array
description: arch of package info
items:
type: string
version:
type: string
description: version of package info
kind:
type: string
description: kind of package info
name:
type: string
description: name of package info
size:
description: Uncompressed package size in bytes
type: integer
runtime:
type: string
description: runtime of package info
base:
type: string
description: base of package info
command:
type: array
description: command of package info
items:
type: string
permissions:
$ref: '#/$defs/ApplicationConfigurationPermissions'
description:
type: string
description: description of package info
ApplicationPermissionsRequest:
type: object
required:
- appID
- xdgDirectories
properties:
appID:
type: string
xdgDirectories:
$ref: '#/$defs/XDGDirectoryPermissions'
CommonOptions:
title: CommonOptions
description: this is common option for Install and InstallFromFile
type: object
required:
- skipInteraction
- force
properties:
skipInteraction:
description: skip interaction, such as 'apt install aa -y'
type: boolean
force:
description: force to overwrite
type: boolean
CommonResult:
title: CommonResult
description: this is common error result of ll-cli command --json
type: object
required:
- message
- code
- type
properties:
type:
description: error type, to indicate client what should be done.
type: string
message:
description: Human readable result message.
type: string
code:
description: We do not use DBus error. We return an error code instead.
Non-zero code indicated errors occurs
and message should be displayed to user.
type: integer
InteractionMessageType:
description: To identify what message to print during interaction.
enum: ['Unknown', 'Install', 'Uninstall', 'Upgrade', 'Downgrade']
PackageManager1RequestInteractionAdditionalMessage:
type: object
description: fill ref string to additional message in requestInteraction
required:
- LocalRef
- RemoteRef
properties:
LocalRef:
type: string
RemoteRef:
type: string
State:
description: main state of current task,
enum:
[
'Unknown',
'Queued',
'Pending',
'Processing',
'PartCompleted',
'Succeed',
'Failed',
'Canceled',
]
SubState:
description: subState of current task,
enum:
[
'Unknown',
'PreAction',
'InstallRuntime',
'InstallBase',
'InstallApplication',
'PostAction',
'Uninstall',
'AllDone',
'PackageManagerDone',
]
PackageManager1InstallLayerFDResult:
$ref: '#/$defs/CommonResult'
PackageManager1InstallParameters:
type: object
description: package manager install parameters
required:
- package
- options
properties:
package:
title: PackageManager1InstallParametersPacakge
type: object
required:
- id
properties:
channel:
type: string
id:
type: string
version:
type: string
modules:
type: array
items:
type: string
repo:
type: string
description: repo alias of package manager install parameters
options:
$ref: '#/$defs/CommonOptions'
PackageManager1PackageTaskResult:
description: package manager task result
allOf:
- $ref: '#/$defs/CommonResult'
properties:
taskObjectPath:
type: string
description: task dbus object path of package manager install
PackageManager1UninstallParameters:
type: object
description: package manager uninstall parameters
required:
- package
- options
properties:
package:
$ref: '#/$defs/PackageManager1Package'
options:
$ref: '#/$defs/CommonOptions'
PackageManager1UpdateParameters:
type: object
description: package manager update result
required:
- packages
properties:
packages:
type: array
description: packages of package manager update
items:
$ref: '#/$defs/PackageManager1Package'
PackageManager1ModifyRepoParameters:
type: object
required:
- defaultRepo
- repos
properties:
defaultRepo:
type: string
description: default repo of package manager modify repo parameters
repos:
type: object
description: repos of of package manager modify repo
additionalProperties:
type: string
PackageManager1ModifyRepoResult:
$ref: '#/$defs/CommonResult'
PackageManager1SearchParameters:
type: object
description: package manager search parameters
required:
- id
- repos
properties:
id:
type: string
description: id of package manager search
repos:
type: array
description: repo of package manager search
items:
type: string
PackageManager1JobInfo:
type: object
description: Get the job result using an ID
allOf:
- $ref: '#/$defs/CommonResult'
required:
- id
properties:
id:
type: string
description: id of job info
PackageManager1SearchResult:
type: object
description: result of package manager search
allOf:
- $ref: '#/$defs/CommonResult'
properties:
packages:
type: object
additionalProperties:
type: array
items:
$ref: '#/$defs/PackageInfoV2'
description: package info of package manager search
PackageManager1PruneResult:
type: object
description: result of package manager search
allOf:
- $ref: '#/$defs/CommonResult'
properties:
packages:
type: array
items:
$ref: '#/$defs/PackageInfoV2'
PackageManager1GetRepoInfoResult:
type: object
description: result of package manager get repo info
allOf:
- $ref: '#/$defs/CommonResult'
required:
- repoInfo
properties:
repoInfo:
title: PackageManager1GetRepoInfoResultRepoInfo
description: result of package manager get repo info
type: object
properties:
defaultRepo:
type: string
description: default repo of package manager get repo info
repos:
type: object
description: repos of package manager get repo info
additionalProperties:
type: string
description: additional properties of package manager get repo info
required:
- defaultRepo
- repos
RepositoryCache:
title: RepositoryCache
type: object
description: storing information of all packages and config of repo
required:
- version
- ll-version
- config
- layers
properties:
version:
type: string
description: version of storage
# const: "1"
# FIXME: quicktype will generate enum class and ignore the hierarchy
# so comparing this value inside code
ll-version:
type: string
description: version of linglong at the time of generating the file
config:
$ref: '#/$defs/RepoConfigV2'
layers:
type: array
items:
type: object
description: stores the full module name with repo name and the corresponding ostree commit
title: RepositoryCacheLayersItem
required:
- repo
- commit
- info
# TODO: maybe we should add the map of module which depends by this item in the future
properties:
repo:
type: string
description: which repo is this app belongs to
deleted:
description: deleted mark
type: boolean
commit:
type: string
description: ostree commit hash
info:
$ref: '#/$defs/PackageInfoV2'
merged:
type: array
items:
type: object
description: Merge multiple modules into one directory
title: RepositoryCacheMergedItem
required:
- id
- modules
- commits
properties:
id:
type: string
description: binary module ostree commit hash
name:
type: string
description: human readable name
binaryCommit:
type: string
description: binary module ostree commit hash
modules:
type: array
description: list of merged module names
items:
type: string
commits:
type: array
description: list of ostree commit hashes for each module
items:
type: string
UpgradeListResult:
title: UpgradeListResult
description: this is upgrade list result of ll-cli upgrade --json
type: object
required:
- id
- old_version
- new_version
properties:
id:
description: id of package.
type: string
old_version:
description: version of current installed.
type: string
new_version:
description: version of latest version in remote repo.
type: string
DialogMessage:
description: |
For interactive with frontend dialog. All message exchange between dialog and
caller should use stdin and stdout. The first four bytes indicate the length
of the message. The rest of the payload is the actual payload.
type: object
required:
- type
- payload
properties:
type:
description: type of dialog message, possible values are ['Handshake', 'Request']
type: string
payload:
description: payload of dialog message, the real payload depends on type
type: string
DialogHandShakePayload:
type: object
required:
- version
properties:
version:
description: |
Minimum protocol version supported by the client.
Current version is 1.0.
1.0 behavior: dialog MUST report self minimal protocol version at program start.
if client not reported protocol version, caller SHOULD kill dialog after timeout.
then, caller will send a directory permission request to dialog. if timeout,
client SHOULD exit immediately. after that, caller will wait for dialog exit
and use dialog exit code to know user allow the request or not. dialog MUST exit
with 0, any other value means user reject the request or dialog internal error and
dialog could output any message to stderr.
type: string
ExportDirs:
type: object
required:
- export-paths
properties:
export-paths:
type: array
items:
type: string
description: path to export
ExtensionDefine:
type: object
required:
- name
- version
- directory
properties:
name:
description: extension name
type: string
version:
description: extension version
type: string
directory:
description: where extension to be mount
type: string
allow_env:
description: the environment variables allow extension to modify
type: object
additionalProperties:
description: default environment variable
type: string
ExtensionImpl:
type: object
properties:
libs:
description: extra ld search path
type: array
items:
type: string
env:
description: environment variables to set when extension effects
type: object
additionalProperties:
type: string
type: object
properties:
# NOTE: "properties" is auto generated by referring all types is $defs