Roadmap for the KOE Source Code

This roadmap lists the top level directories in the KOE source distribution and briefly describes their contents. The roadmap is intended to make it easier to find your way around in the code.

config/

Contains configuration files, including those for access controls, for plugin configuration, and for the koeboot utility.

demos/

Several more elaborate examples that demonstrate the kinds of experiments we are performing with the KOE.

examples/

A collection of simple, self-contained example KP applications.

kernel/

The central process for a service station. Includes implementation of the Receiver, the KOS namespace, the KOS administrative interface, and other internal interfaces. kernel.py is the script that starts the KOS kernel.

koe/

A Python package that contains code shared by several KOE components. See the note on the koe package below. There are several subpackages:

common

A hodge-podge of libraries to be used by KPs and code shared by different parts of the KOS implementation. The generally useful code is documented.

interfaces

The ISL files that define interfaces between KOE components.

interfaces.stubs

Contains the stub code generated by the ILU stubber.

pythonlib

Contains a few modules that replace modules in the standard Python distribution, primarily because we have experimental changes or because we depend on bug fixes that have not been released yet.

tools.visu

Code use by the visualizer.

tools.xml

Some general XML support modules used in one of the demonstrations.

plugins/

Several example KOS plugins.

supervisor/

Implementation of the KP supervisor and the KP restricted execution environment. The supervisor is launched by kpstarter.py, which is invoked by the kernel.

supervisor/proxies

KP restricted execution mode proxy modules, current urllib and socket. See the Note on KP rexec proxies.

testcases/

Many small KPs that exercise specific parts of the KOE.

tools/

User tools to launch KPs, monitor the namespace, and perform many other tasks.

var/

Stores data files used by the worldroot, including the ILU string-binding handle, or SBH, for the worldroot.

Note on KP rexec proxies

A proxy runs in unrestricted mode and exports a 'safe' interface to some set of operations. For example, the urllib proxy provides an implementation of the urlopen that can be used to limit which URLs a KP is allowed to open.

The proxy implementation can be used to allow a KOS administrator to add modules to the restricted environment which require non-restricted implementations. In general, you can implement a proxy that lets a KP call some protected function, e.g. open a file or exec a process, but checks the arguments to those functions before making the call.

At this time, the proxy architecture is not fully documented. The doc string in the file supervisor/KPRExec.py describes it in greater detail, but it still has some gaps.

Note on the koe package

Although the code is in a package, KPs do not yet have access to packages. (The implementation of restricted execution used by KPs does not support Python packages.) Instead, a KP can import modules directly from koe.common. The other packages should not be needed from a KP.

The practical impact of the koe package structure is that standalone utilties and plugins must import from a package, while the koe.common package is implicitly on a KP's path. For example, in a plugin you might see

from koe.common import nstools
from koe.interfaces.stubs import GenericAPI__skel

while in a KP, you would simply see:

import nstools

The KP supervisor automatically manages the binding of ILU stub classes, so a KP would not import from koe.interfaces. However, KPs do need to use the exceptions defined by ILU interfaces and this policy prevents them from doing so. The work-around is described in the catching exceptions section of the KP interface documentation.