docs: add api/dbus and docs/TODO.md

Signed-off-by: black-desk <me@black-desk.cn>

api/dbus/org.desktopspec.ApplicationManager1.Application.xml

@@ -0,0 +1,104 @@
+<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" "https://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
+<node>
+    <interface name="org.desktopspec.ApplicationManager1.Application">
+        <annotation
+                name="org.freedesktop.DBus.Description"
+                value="This interface is designed to
+                       provide a dbus interface of desktop file.
+                       Missing fields will be added later."
+        />
+
+        <method name="Launch">
+            <arg type="s" name="action" direction="in" />
+            <arg type="as" name="fields" direction="in" />
+            <arg type="o" name="job" direction="out" />
+
+            <arg type="a{sv}" name="options" direction="in"/>
+
+            <annotation
+                name="org.freedesktop.DBus.Description"
+                value="Given an action identifier,
+                       and some fields (file path or URI),
+                       this method will launch this application,
+                       and the object path of the job launching application.
+                       Result of that job is a object path
+                       of the new application instance.
+                       If that job failed, the result is a bool `false`.
+
+                       Extra options can be passed in `options` argument:
+                       1. `uid` (type u):
+                          The user id as who is that application will be run.
+                          This option might request a polikit authentication."
+            />
+        </method>
+
+        <property type="a{sa{ua{sh}}}" name="Icons" access="read">
+            <annotation
+                name="org.freedesktop.DBus.Description"
+                value="The type of this property is
+                       map[action(string)]map[size(uint)]map[format(string)]fd.
+
+                       Format can be `png`, `svg`, `xpm`, `dci` or `icon`
+                       refering to the png/svg/xpm/dci format of icon files,
+                       as well as the `.icon` file contain the extra icon-data.
+
+                       NOTE:
+                       1. `action` is an action identifier
+                          which is the id of
+                          additional applications actions key.
+                          When `action` is emtpy,
+                          this method return icon of the main desktop entry.
+                          Check https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s11.html#extra-actions-identifier
+                          for futher infomation.
+                       2. `.icon` is a text file with some metadata.
+                          Check https://specifications.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html#file_formats
+                          for futher infomation.
+                       3. Check https://github.com/linuxdeepin/deepin-specifications
+                          for futher infomation of dci icon format."
+            />
+        </method>
+
+        <property name="Actions" type="as" access="read">
+           <annotation
+                name="org.freedesktop.DBus.Description"
+                value="Names of all action identifiers of this application.
+                       Check https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#extra-actions
+                       for futher information."
+            />
+        </property>
+
+        <method name="GetActionName">
+            <arg name="identifier" type="s" direction="in"/>
+            <arg name="env" type="as" direction="in"/> 
+            <arg name="name" type="s" direction="out"/>
+            <annotation
+                name="org.freedesktop.DBus.Description"
+                value="Given an action identifier
+                       and optional locale-releate environments,
+                       this method return the localized value of Name of
+                       that action.
+                       If env is not passed,
+                       this method will use the locale config of that user."
+            />
+        </method>
+
+
+        <property name="AutoStart" type="b" access="readwrite"/>
+
+        <property name="Instances" type="ao" access="read">
+            <annotation
+                name="org.freedesktop.DBus.Description"
+                value="All instances of this application."
+            />
+        </property>
+
+        <property name="ID" type="s" access="read">
+            <annotation
+                name="org.freedesktop.DBus.Description"
+                value="The desktop file id of this application.
+                       Check https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#desktop-file-id
+                       for futher infomation."
+            />
+        </property>
+    </interface>
+</node>

api/dbus/org.desktopspec.ApplicationManager1.Instance.xml

@@ -0,0 +1,26 @@
+<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" "https://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
+<node>
+    <interface name="org.desktopspec.ApplicationManager1.Instance">
+        <property name="Application" type="o" access="read">
+            <annotation
+                name="org.freedesktop.DBus.Description"
+                value="Object path of the Application.
+                       That DBus object will impelement
+                       org.desktopspec.ApplicationManager1.Application."
+            />
+        </property>
+
+        <property name="SystemdUnitPath" type="o" access="read">
+            <annotation
+                name="org.freedesktop.DBus.Description"
+                value="The systemd unit object path of this instance
+                       under systemd user daemon.
+                       Some other DE compoments can use this path to
+                       use the cgroup interface provided by systemd.
+                       NOTE:
+                       This property MIGHT be empty
+                       if this instance is not managed by systemd."
+            />
+        </property>
+    </interface>
+</node>

api/dbus/org.desktopspec.ApplicationManager1.xml

@@ -0,0 +1,49 @@
+<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" "https://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
+<node>
+    <interface name="org.desktopspec.ApplicationManager1">
+        <property type="ao" access="read" name="List" />
+
+        <method name="Application">
+            <arg type="s" name="id" direction="in" />
+            <arg type="o" name="application" direction="out" />
+        </method>
+
+        <method name="Identify">
+            <arg type="h" name="pidfd" direction="in" />
+
+            <arg type="s" name="id" direction="out" />
+            <arg type="o" name="application" direction="out" />
+            <arg type="o" name="application_instance" direction="out" />
+
+            <annotation
+                name="org.freedesktop.DBus.Description"
+                value="Given a pidfd,
+                       this method return a destkop file id,
+                       an application instance object path,
+                       as well as an application object path.
+
+                       NOTE:
+                       1. You should use pidfd_open(2) to get a pidfd."
+            />
+        </method>
+
+        <method name="Launch">
+            <arg type="s" name="id" direction="in" />
+            <arg type="s" name="action" direction="in" />
+            <arg type="as" name="fields" direction="in" />
+            <arg type="a{sv}" name="options" direction="in" />
+
+            <arg type="o" name="job" direction="out" />
+
+            <annotation
+                name="org.freedesktop.DBus.Description"
+                value="Given a desktop file id,
+                       this method will launch a desktop application.
+
+                       Check description of the `Launch` method in
+                       `org.desktopspec.ApplicationManager1.Application`
+                       interface for futher infomation."
+            />
+        </method>
+    </interface>
+</node>

api/dbus/org.desktopspec.JobManager1.Job.xml

@@ -0,0 +1,46 @@
+<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" "https://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
+<node>
+    <interface name="org.desktopspec.JobManager1.Job">
+        <property name="Status" type="s" access="read">
+            <annotation
+                name="org.freedesktop.DBus.Description"
+                value="Value of `Status` is one of
+                       `pending`, `working`, `done`,
+                       `pasuing`, `paused`, `resuming`,
+                       `canceled` and `failed`."
+            />
+        </property>
+
+        <method name="Cancel">
+            <annotation
+                name="org.freedesktop.DBus.Description"
+                value="Success call to this method will
+                       change the Status of this Job to `canceled`.
+                       Then after some time this method call return,
+                       this Job will be removed.
+                       Then the signal JobRemoved of org.desktopspec.JobManager1
+                       will be emitted."
+            />
+        </method>
+        <method name="Pause">
+            <annotation
+                name="org.freedesktop.DBus.Description"
+                value="Success call to this method will
+                       change the Status of this Job to `pausing`.
+                       Then after some time this method call return,
+                       Status will change to `paused`."
+            />
+        </method>
+
+        <method name="Resume">
+            <annotation
+                name="org.freedesktop.DBus.Description"
+                value="Success call to this method will
+                       change the Status of this Job to `resuming`.
+                       Resuming Jobs will be queued along with pending Jobs.
+                       Then after some time this method call return,
+                       Status will change to `working`."
+            />
+        </method>
+    </interface>
+</node>

api/dbus/org.desktopspec.JobManager1.xml

@@ -0,0 +1,46 @@
+<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" "https://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
+<node>
+    <interface name="org.desktopspec.JobManager1">
+        <annotation
+            name="org.freedesktop.DBus.Description"
+            value="All method might block will return a DBus object path,
+                   which implement org.desktopspec.JobManager1.Job.
+                   This interface is design to provide some DBus signals to help
+                   caller to watch the Jobs they invoked.
+                   Caller should not interst in all the Jobs, as there are some
+                   Jobs not created by them.
+                   So the method to list all exsiting Jobs is NOT provided.
+                   NOTE:
+                   Signal emitted by this interface MIGHT be peer-to-peer."
+        />
+
+        <signal name="JobNew">
+            <arg type="o" name="job" />
+            <arg type="o" name="source" />
+
+            <annotation
+                name="org.freedesktop.DBus.Description"
+                value="`source` is the DBus object produce this job."
+            />
+        </signal>
+        <signal name="JobRemoved">
+            <arg type="o" name="job" />
+            <arg type="s" name="status" />
+            <arg type="s" name="message" />
+            <arg type="v" name="result" />
+
+            <annotation
+                name="org.freedesktop.DBus.Description"
+                value="This signal report the job remove event.
+                       `status` is the `status` porperty of that Job
+                       when it got removed.
+                       `message` is the human readable message
+                       for caller to report to user or just simple logging.
+                       `result` is the result this job produce if it success.
+                       Method that return an object of Job
+                       should always have document
+                       about the type and meaning of the `result`."
+            />
+        </signal>
+    </interface>
+</node>

docs/TODO.md

@@ -0,0 +1,103 @@
+# AM重构计划
+
+目前对AM应该有怎么样的特性、以及其负责的边界，
+已经在[AM-ICU房间][1]中经过了详细的讨论。
+已经到了可以着手进行初步的设计和评审工作的阶段。
+
+[1]: https://matrix.to/#/!WBkiaAZKeeKzerJEZQ:deepin.org?via=deepin.org&via=matrix.org&via=mozilla.org
+
+## 背景
+
+由于目前老AM项目中尚有dock和launcher项目的逻辑，
+所以在重构时，
+需要同步地将dock和launcher中属于后台服务部分的逻辑写回对应项目中去。
+该部分工作会与AM的重构工作同步进行，由负责dock和launcher的研发人员完成。
+这两个任务与AM的重构工作不应该产生强的依赖关系。
+
+基于以上背景，老的AM并不会直接被移除，我们将新建一个项目完成新AM的编写。
+完成其主要功能以后再将老AM中的启动应用功能移除，
+并将dock和launcher中启动应用的部分逻辑切换到新AM提供的DBus接口。
+
+老AM中launcher和dock的后端逻辑不会进行任何更改，
+直到等待launcher和dock已经不再依赖老AM后，
+彻底将旧AM从系统中移除。
+
+## AM的主要功能
+
+1. DDE的desktop文件管理器。
+
+   所有需要获取Desktop文件的进程，都应该通过AM来进行这个操作。
+   AM会提供两套接口完成对desktop文件的访问以及管理：
+
+   1. DBus
+   2. fuse 用于完全实现XDG兼容。\[暂不实现\]
+
+   这两套接口都需要考虑接口的调用者是从容器中访问的情况。
+
+2. DDE的应用执行者。
+
+   需要提供DBus接口并更新dde-open。
+
+## 工作记录
+
+由参与AM重构计划的研发人员完成的主要的工作有以下几方面，
+可以拆分为几个阶段来完成：
+
+- 准备
+  - [x] 完成AM的DBus API设计文档（@black-desk）；
+
+    本次AM共计需要完成5个DBus接口:
+
+    1. [`org.desktopspec.ApplicationManager1`](../api/dbus/org.desktopspec.ApplicationManager1.xml)
+    2. [`org.desktopspec.ApplicationManager1.Application`](../api/dbus/org.desktopspec.ApplicationManager1.Application.xml)
+    3. [`org.desktopspec.ApplicationManager1.Instance`](../api/dbus/org.desktopspec.ApplicationManager1.Instance.xml)
+    4. [`org.desktopspec.JobManager1`](../api/dbus/org.desktopspec.JobManager1.xml)
+    5. [`org.desktopspec.JobManager1.Job`](../api/dbus/org.desktopspec.JobManager1.Job.xml)
+
+  - [ ] 以上接口设计需要通过评审。
+
+  - [ ] 完成AM的主要项目结构搭建；
+
+    框架完成后需要通过评审。
+
+- [ ] 主要功能开发
+  - [ ] 应用列表；
+  - [ ] 启动应用；
+  - [ ] 从PID获取AppID；
+  - [ ] 正在运行的应用列表；
+  - [ ] 崩溃后恢复现场；
+
+- [ ] launcher/dock迁移 
+  
+  更改launcher和dock中启动应用部分的代码，使用新dock来实现。
+  并删除老AM中启动应用相关的代码。
+
+- [ ] 测试工作 
+
+  进行
+
+  - [ ] dock
+  - [ ] launcher
+  - [ ] dde-open/xdg-open
+  - [ ] 文件管理器
+  - [ ] 浏览器
+
+  等桌面组件的基础功能测试，bug修复。
+
+- [ ] hook功能开发
+
+  该功能的开发主要是为了防止应用从配置好的cgroup中逃逸。
+
+  1. 完成App运行前hook插件体系的实现；
+  2. 重要插件实现：
+     - [ ] cgroup锁定插件的实现；(@black-desk) 
+
+       <https://github.com/black-desk/djail>
+
+     - [ ] dbus代理插件；(@black-desk) 
+
+       使用flatpak提供的xdg-dbus-proxy实现一个不可交互的dbus代理，
+       目前主要用于屏蔽systemd用户实例提供的cgroup移动功能。
+
+       使用一个具有特权的二进制创建新的mount namepsace，
+       通过挂载将proxy提供的socket bind到对应位置。