aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorThomas Touhey <thomas@touhey.fr>2021-06-07 20:57:00 +0200
committerThomas Touhey <thomas@touhey.fr>2021-06-07 20:57:00 +0200
commitb38619c041a53471a2256adaade863286861916c (patch)
tree1bcebe07deb986e5e60fe4248a36f601d8fb7897
parent41a947fa67e111c71c8cfbf81da3b4adcf724363 (diff)
Removed 'just' some words, see justsimply.dev for more on the background
-rw-r--r--docs/explain/encodings.rst6
-rw-r--r--docs/explain/modem-protocols.rst15
-rw-r--r--docs/explain/modem/gps-trilaterate.lua9
-rw-r--r--docs/explain/modem/ldd.rst7
-rw-r--r--docs/explain/modem/oneos.rst12
-rw-r--r--docs/explain/modem/opus.rst6
-rw-r--r--docs/howto/daemon.rst2
-rw-r--r--docs/index.rst8
-rw-r--r--docs/system.rst2
-rw-r--r--docs/system/gpsd.rst2
-rw-r--r--docs/system/pkgd.rst2
-rw-r--r--docs/system/process/contexts.rst64
-rw-r--r--docs/system/process/manager.rst10
-rw-r--r--docs/system/process/torpcname.lua81
-rw-r--r--docs/system/startup/startup-api.rst16
15 files changed, 168 insertions, 74 deletions
diff --git a/docs/explain/encodings.rst b/docs/explain/encodings.rst
index 69a5f02..626cbdc 100644
--- a/docs/explain/encodings.rst
+++ b/docs/explain/encodings.rst
@@ -14,8 +14,8 @@ Lua strings are nothing more than sequences of bytes with no validation
or transformation; interpreting them as text is up to the programs and
native APIs.
-For simplification, we'll suppose that encodings are simply a way to encode
-a sequence of codepoints, where each codepoint is a numerical value
+For the sake of simplicity, we'll consider that encodings are a way to
+encode a sequence of codepoints, where each codepoint is a numerical value
representing a character within bounds, over a sequence of bytes, and that
for a sequence of codepoints, there is exactly one way to represent it
over a sequence of bytes. Note that this doesn't mean a text has only one
@@ -53,7 +53,7 @@ characters; the table above corresponds to the 8x11 glyphs defined in the
mod.
This comes from the fact that Cobalt, the LuaJ fork specific to ComputerCraft,
-i.e. the Lua interpreter, decodes and encodes a Lua string by simply mapping
+i.e. the Lua interpreter, decodes and encodes a Lua string by mapping
byte values to Unicode codepoints; see `LuaString.decode`_.
This encoding is used in every string passed on to the Lua code, and
diff --git a/docs/explain/modem-protocols.rst b/docs/explain/modem-protocols.rst
index 0ebe3c0..acc4fe0 100644
--- a/docs/explain/modem-protocols.rst
+++ b/docs/explain/modem-protocols.rst
@@ -26,7 +26,7 @@ or OPUS OS, and also has limits which we will describe in this section.
Note however that Rednet is not the only protocol of its kind, and others
have been created either for answering Rednet's identified weaknesses,
-or simply for funsies.
+or for funsies.
Rednet
------
@@ -64,10 +64,9 @@ the “reply channel” is used by filling it with the computer ID.
cause other problems such as intricated filesystems between the
two computers having the same ID.
- Plus, the computer ID can be spoofed; the most straightforward way
- of doing this is by reimplementing rednet over the modem API but
- getting the ID to use through other means, such as having a
- ``idToSpoof`` constant.
+ Plus, the computer ID can be spoofed; one way to do this in CraftOS
+ is to reimplement rednet over the modem API but getting the ID to use
+ through other means, such as having a ``idToSpoof`` constant.
On a Rednet-enabled device, two channels are opened by default for receiving
messages: the broadcast channel, and the modem channel with the computer ID
@@ -77,9 +76,9 @@ messages or answers; see `rednet.open`_.
.. warning::
Notice that there is no limit to the ID a computer can be assigned except
- the Java ``int`` type maximum value, which is :math:`2^{32} - 1`, where the modem
- number can only between :math:`0` and :math:`2^{16} - 1`. There are two
- cases that might cause unexpected behaviours:
+ the Java ``int`` type maximum value, which is :math:`2^{32} - 1`, where the
+ modem number can only between :math:`0` and :math:`2^{16} - 1`. There are
+ two cases that might cause unexpected behaviours:
* The computer ID exceeds :math:`2^{16} - 1`, which is not a valid port
number.
diff --git a/docs/explain/modem/gps-trilaterate.lua b/docs/explain/modem/gps-trilaterate.lua
index e2cbd40..4db4d40 100644
--- a/docs/explain/modem/gps-trilaterate.lua
+++ b/docs/explain/modem/gps-trilaterate.lua
@@ -1,3 +1,12 @@
+-- gps-trilaterate.lua, a module defining a GPS trilateration function
+-- for ComputerCraft.
+--
+-- Copyright (C) 2021 Thomas Touhey <thomas@touhey.fr>
+-- This file is part of the thox project, which is MIT-licensed.
+--
+-- For more information, consult the following page:
+-- <https://thox.madefor.cc/explain/modem/gps.html#trilateration>_
+
local function trilaterate(ax, ay, az, bx, by, bz, cx, cy, cz, da, db, dc)
local dab2, dab, ex, ey
local u, vx, vy
diff --git a/docs/explain/modem/ldd.rst b/docs/explain/modem/ldd.rst
index c7ffb32..bedb963 100644
--- a/docs/explain/modem/ldd.rst
+++ b/docs/explain/modem/ldd.rst
@@ -18,6 +18,13 @@ their software.
Wireless redstone
-----------------
+This protocol is a port protocol running on port 1005. It is a protocol that
+has two components:
+
+ * Requests to control the redstone logical outputs on given directions
+ (left to right, front to back, top to bottom).
+ * Events when updates on redstone logical inputs occur.
+
.. todo::
Describe the program and the protocol.
diff --git a/docs/explain/modem/oneos.rst b/docs/explain/modem/oneos.rst
index a456777..580c2eb 100644
--- a/docs/explain/modem/oneos.rst
+++ b/docs/explain/modem/oneos.rst
@@ -468,12 +468,12 @@ The issues are the following:
This can be mitigated by checking, at the ``TransmitSend`` message
reception if the file has already been approved.
* The ``TransmitRequest``/``TransmitRequestReply`` step is actually
- completely optional, as the utility will just gladly save any file you
+ completely optional, as the utility will gladly save any file you
send to it. The mitigation quoted before should do the trick, as it
requires the sender to get its request approved first.
* In order to save the file, the final path is obtained by appending the
given file name to “/Desktop/Documents/” without sanitizing the input.
- This allows for `path traversal`_ attacks by simply setting the filename
+ This allows for `path traversal`_ attacks by setting the filename
in the ``TransmitSend`` step to “../../startup” for example.
Combined with the previous security vulnerability, this gives you a
wormable attack that can affect any OneOS device as soon as it is
@@ -491,7 +491,7 @@ usages.
Ultimate Door Lock Protocol
---------------------------
-`Ultimate Door Lock`_, simply known as Door Lock on OneOS, is a program for
+`Ultimate Door Lock`_, also known as Door Lock on OneOS, is a program for
locking doors using dedicated Pocket Computers (referred to as PDA in the code),
which will (only) serve as “keys”, like NFC-enabled devices in the real world.
@@ -521,12 +521,12 @@ The application is obviously security sensitive, and takes that fact into
account as in case of error, the door stays locked. However, there are
**major security issues** to this system:
- * The PDA registration is enabled at all time; this means you can just
+ * The PDA registration is enabled at all time; this means you can
put a disk drive next to the computer from the outside, and have your
PDA registered; a mitigation would be to only allow registration at
certain times.
* The secret between the PDA and the door lock, called “fingerprint”,
- can be very simply extracted from any PDA in wireless range by emitting
+ can be extracted from any PDA in wireless range by emitting
a ping and gathering fingerprints from nearby devices, and try them
out in surrounding doors; this is actually a real world issue as well,
with attackers `abusing credit card NFC`_ in public spaces. A mitigation
@@ -563,7 +563,7 @@ The protocol uses three modem channels:
These three channels are used for exchanging OneOS messages (see
:ref:`modem-oneos-message`).
-On the doorlock ping channel, the content is simply the “Ping!” string.
+On the doorlock ping channel, the content is the “Ping!” string.
On the doorlock request channel, the content is the fingerprint as a string,
and on the doorlock reply channel, the content is a boolean which equals
either ``true`` if the door has been unlocked (whitelisted fingerprint and
diff --git a/docs/explain/modem/opus.rst b/docs/explain/modem/opus.rst
index 2f8a33b..1576fa1 100644
--- a/docs/explain/modem/opus.rst
+++ b/docs/explain/modem/opus.rst
@@ -542,7 +542,7 @@ OPUS OS samba protocol
The files application on a ``netfs`` mount, which corresponds to
the native samba client.
-The OPUS OS samba protocol is a simple RPC protocol specialized in filesystem
+The OPUS OS samba protocol is an RPC protocol specialized in filesystem
operations, by proxying the global ``_G.fs`` module with special treatment
of file handles (as modem messages don't carry objects).
@@ -685,8 +685,8 @@ OPUS OS proxy protocol
.. image:: opus-proxy-bpmn.png
-The OPUS OS proxy protocol is a simple and synchronous RPC protocol for
-executing procedures from a trusted device. It uses modem channel 188, and
+The OPUS OS proxy protocol is a synchronous RPC protocol for executing
+procedures from a trusted device. It uses modem channel 188, and
OPUS OS transport; see :ref:`modem-opus-transport`.
Once the connection is setup, the client starts by selecting an API, by
diff --git a/docs/howto/daemon.rst b/docs/howto/daemon.rst
index 625da8f..0d45b6e 100644
--- a/docs/howto/daemon.rst
+++ b/docs/howto/daemon.rst
@@ -11,7 +11,7 @@ In order to make a daemon, the easiest way is probably to use the ``daemon``
library by requiring it. The result of this requirement process is an object
which you can use to bind functions and run the call dispatcher.
-A simple example of using this module is the following:
+An example of using this module is the following:
.. code-block:: lua
diff --git a/docs/index.rst b/docs/index.rst
index 0cb4f1c..c67e8a7 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,8 +1,8 @@
-thox, a simple multi-tasking OS for ComputerCraft
-=================================================
+thox, a multi-tasking OS for ComputerCraft
+==========================================
-thox is a simple operating system for `ComputerCraft`_ providing
-pre-emptive multitasking, secure thread sandboxing and simple IPC.
+thox is an operating system for `ComputerCraft`_ providing
+pre-emptive multitasking, secure thread sandboxing and modern IPC facilities.
The source repository is available `on my forge
<https://forge.touhey.org/cc/thox.git/>`_.
diff --git a/docs/system.rst b/docs/system.rst
index 1042955..2779793 100644
--- a/docs/system.rst
+++ b/docs/system.rst
@@ -36,8 +36,6 @@ components.
* An HTTP and websocket management daemon.
* A terminal/monitor management daemon, for managing inter-mod
screen output and keyboard / clipboard input.
- * A package management daemon. For now we can just concentrate
- on building distributions statically.
* Virtualization guest package for common emulators, such as
CCEmuX, for adding and removing peripherals, opening other
machines, etc.
diff --git a/docs/system/gpsd.rst b/docs/system/gpsd.rst
index 4ef6dc5..c0854f7 100644
--- a/docs/system/gpsd.rst
+++ b/docs/system/gpsd.rst
@@ -19,7 +19,7 @@ their position is permitted through the GPS daemon.
* Should we share our position through the protocol.
Describe what we mean by peer-to-peer, mostly in case of wireless modems
- only and no ender modems (since the later are just like cheated…).
+ only and no ender modems (since the latter are far too powerful…).
Say its a bad idea to share the position when thox runs on a pocket
computer.
diff --git a/docs/system/pkgd.rst b/docs/system/pkgd.rst
index 516e141..c182945 100644
--- a/docs/system/pkgd.rst
+++ b/docs/system/pkgd.rst
@@ -4,7 +4,7 @@ pkgd: the thox package management daemon
========================================
thox manages the system through the filesystem using a dedicated package
-manager, simply named pkgd for "package (management) daemon". The goal of
+manager, named pkgd for "package (management) daemon". The goal of
such a software, to the end user, is to:
* Install features on a per-need basis, with dependencies.
diff --git a/docs/system/process/contexts.rst b/docs/system/process/contexts.rst
index 10432ae..c57eff3 100644
--- a/docs/system/process/contexts.rst
+++ b/docs/system/process/contexts.rst
@@ -4,7 +4,7 @@ thox contexts and interactions
Inter-process communication (IPC) serves, from a process's point of view, for
communicating with the hardware and other processes, allowing them to
cooperate to accomplish a task. It is accomplished in thox using two
-simple mechanisms:
+mechanisms:
* `Remote procedure call`_ (RPC) calls.
* Message queues (*not implemented yet*).
@@ -148,18 +148,23 @@ unbind a name using :lua:func:`os.rpc.unbind`.
RPC names
~~~~~~~~~
-Names are a dot-joined collection of name components, which are
+Names are a dot-joined collection of one or more name components, which are
**non-empty strings of letters and digits**, not beginning with
-a digit and not being a Lua reserved word.
+a digit and not being one of the following reserved words:
+
+ ``and``, ``break``, ``do``, ``else``, ``elseif``, ``end``, ``false``,
+ ``for``, ``function``, ``goto``, ``if``, ``in``, ``local``, ``nil``,
+ ``not``, ``or``, ``repeat``, ``return``, ``then``, ``true``, ``until``,
+ ``while``
A Name:
- * **Can end with an underscore**; note that only the last name component
- can end with an underscore, e.g. ``fs_.open`` is not allowed.
- * **Must neither end with an empty component** (i.e. with a dot) nor must the
- last component be composed solely of an underscore; for example,
+ * **Can end with an underscore**. Note that only the last name component
+ can end with an underscore; for example, ``fs_.open`` is not allowed.
+ * **Must neither end with an empty component** (i.e. with a dot) **nor must
+ the last component be composed solely of an underscore**; for example,
``fs_`` and ``fs.open_`` are allowed, where ``_`` or ``fs._`` are not.
- * **Is of arbitrary length** [#rpcnamearbitrarylength]_.
+ * **Is of non-zero arbitrary length** [#rpcnamearbitrarylength]_.
* **Is case-insensitive**, which implies that the callee will receive a
lower-cased version of it; e.g. ``FS.GetSpaceLeft``, ``FS.GETSPACELEFT``
and ``fs.getspaceleft`` will all be received by the callee as
@@ -172,17 +177,10 @@ lookaheads) is the following:
::
- /(?!.*\.\_?$)((?!and|break|...|until|while)([a-z][a-z0-9]*)\.?)*\_?/gi
-
-Reserved words are the following:
-
- and, break, do, else, elseif, end, false, for, function,
- goto, if, in, local, nil, not, or, repeat, return, then,
- true, until, while
+ /(?!.*\.\_?$)((?!and|break|do|else|elseif|end|false|for|function|goto|if|in|local|nil|not|or|repeat|return|then|true|until|while)([a-z][a-z0-9]*)\.?)*\_?/gi
-Note that these names have no arbitrary maximum length; .
-However, to avoid confusions, **RPC names are case-insensitive**, which means
-that ``fs.getspaceleft`` and ``FS.GetSpaceLeft`` lead to the same endpoint.
+A Lua function to validate and return the canonicalized RPC name can be
+found in :download:`torpcname.lua`.
Some valid and invalid identifiers are the following:
@@ -195,10 +193,15 @@ Some valid and invalid identifiers are the following:
| ``os.module``
| ``how.deep.does.this.go``
| ``my.function2``
+ | ``my.function2_``
+ | ``my_``
- | ``for``
| ``123hello``
| ``hello.2theworld``
| ``my.gawd$``
+ | ``my_.function2``
+ | ``my._``
+ | ``_``
The rationale behind this definition is to be able to integrate these
identifiers into native code using the :lua:class:`os.rpc` prefix, for example
@@ -208,9 +211,9 @@ difference between ``fs.GetSpaceLeft`` and ``fs.getspaceleft`` could generate,
leading to potential security problems; see `typosquatting`_ for a real world
problem alike what this mitigation is addressing.
-Notice that while this API is asynchronous, most simple programs will only
-need to call RPC functions synchronously; to simplify this, the user can
-use the :lua:class:`os.rpc` object.
+Notice that while this API is asynchronous, most of the time, processes will
+want to call RPC functions synchronously; to make this more accessible,
+one can use the :lua:class:`os.rpc` object.
.. _rpc-status-codes:
@@ -237,14 +240,15 @@ Special status codes are the following:
Sharing contexts
~~~~~~~~~~~~~~~~
-While some RPC calls return "simple" values, such as nil values, strings,
-numbers, and so on, some other share contexts.
+While some RPC calls return scalar values, such as nil values, strings and
+numbers, some other share contexts.
Sharing a context means providing the caller an access to a given context.
-The condition for sharing a context is simple:
+thox uses the *"underscore means sharing"* ideology, which is stated
+as followed:
**If the name of the RPC procedure ends with an underscore, then the
- first argument is the context being shared**.
+ first argument in the answer is the context being shared**.
So for example, ``math.add`` will not share a context, where ``fs.open_``
will. Let's take this last RPC call, where the callee creates
@@ -268,16 +272,16 @@ the conversion while sharing the context.
.. note::
- The "underscore means sharing" design is the simplest solution to the
+ The *"underscore means sharing"* design is the simplest solution to the
following design problem: how does the process manager know if a number
- the callee has just answered to a call was intended to be a number or
- a context number, which needs to be shared and translated between
- processes?
+ the callee has transmitted as an answer to a call was intended to be a
+ scalar or a context number, which needs to be shared and translated
+ between processes?
The following other possibilities were considered:
* Making every argument to :lua:func:`os.answer` (except the call
- identifier) a table, composed of one elements for simple arguments
+ identifier) a table, composed of one elements for scalar arguments
(e.g. ``{5}`` or ``{"hello"}`` and two elements for contexts to
be shared (e.g. ``{5, "ctx"}``).
diff --git a/docs/system/process/manager.rst b/docs/system/process/manager.rst
index 8c2e479..ad69d98 100644
--- a/docs/system/process/manager.rst
+++ b/docs/system/process/manager.rst
@@ -93,7 +93,7 @@ functions bring on top of the system ones:
* :lua:func:`coroutine.resume` resumes the coroutine using the real
resuming function until it yields. Then:
- * If the coroutine has died, then it just returns the received arguments
+ * If the coroutine has died, then it returns the received arguments
received from the real “resume” function to the caller, as the special
value isn't here.
* Otherwise, if the coroutine has yielded, then it extracts the special
@@ -109,7 +109,7 @@ All of this behaviour is transparent to the user. Note that instead of calling
automatically yield system calls but returns them to the caller, which
can then imitate the system (useful for testing), transmit the calls and
answers while sharing time between coroutines in a collaborative fashion
-(useful for making simple daemons), log system calls and answers in `strace`_
+(useful when making daemons), log system calls and answers in `strace`_
fashion, and so on.
.. todo::
@@ -119,9 +119,9 @@ fashion, and so on.
Also, I should shift from loading the program outside with a distinct
environment to start a process directly, and setup the sandbox and
load the file from within the created function! This would allow me
- more liberties and make the whole thing more simple; this means that
- the :lua:meth:`startup.ProcessManager:add` method would take a function
- instead of a program, and just run it inside a coroutine and that's all.
+ more freedom and make the whole thing simpler; this means that
+ the :lua:meth:`startup.ProcessManager:add` method would only
+ take a function (instead of a program) and run it inside a coroutine.
Startup and main loop
---------------------
diff --git a/docs/system/process/torpcname.lua b/docs/system/process/torpcname.lua
new file mode 100644
index 0000000..ffd46e8
--- /dev/null
+++ b/docs/system/process/torpcname.lua
@@ -0,0 +1,81 @@
+-- torpcname.lua, a module defining an RPC name validation function.
+--
+-- Copyright (C) 2021 Thomas Touhey <thomas@touhey.fr>
+-- This file is part of the thox project, which is MIT-licensed.
+--
+-- For more information, consult the following page:
+-- <https://thox.madefor.cc/system/process/contexts.html#rpc-names>_
+
+function toRPCName(name)
+ local name = string.lower(tostring(name))
+ local endsWithUnderscore = false
+ local forbiddenComponents = {'and', 'break', 'do',
+ 'else', 'elseif', 'end', 'false', 'for', 'function', 'goto',
+ 'if', 'in', 'local', 'nil', 'not', 'or', 'repeat', 'return',
+ 'then', 'true', 'until', 'while'}
+
+ -- We check here if the name finishes with an underscore.
+
+ if string.sub(name, -1) == "_" then
+ endsWithUnderscore = true
+ name = string.sub(name, 1, -2)
+ end
+
+ -- Checks being made here:
+ --
+ -- * No character other than letters, digits and dots are present.
+ -- * No name component start with a digit.
+ -- * No name component is empty.
+ -- * No name component is a reserved word.
+
+ if string.match(name, '^[a-z0-9.]*$') ~= name then
+ error("there is a forbidden character")
+
+ return nil
+ end
+
+ do
+ local cname = "." .. name .. "."
+
+ if string.match(cname, '[.][0-9]') then
+ error("a name component starts with a digit")
+
+ return nil
+ elseif string.find(cname, '[.][.]') ~= nil then
+ error("a name component is empty")
+
+ return nil
+ end
+
+ for _, component in pairs(forbiddenComponents) do
+ if string.find(cname, '[.]' .. component .. '[.]') ~= nil then
+ error("a forbidden name component was found: " .. component)
+
+ return nil
+ end
+ end
+ end
+
+ if endsWithUnderscore then
+ name = name .. '_'
+ end
+
+ return name
+end
+
+-- Tests for checking if the function defined above works.
+
+for _, name in pairs({'sleep', 'os.module', 'how.deep.DOES.this.go',
+ 'my.function2', 'my.function2_', 'my_', '_', 'for', '123hello',
+ 'hello.2theworld', 'my.gawd$', 'my_.function2', 'my._', 'my..god',
+ 'FS.GetSpaceLeft', 'FS.GETSPACELEFT', 'fs.getspaceleft'}) do
+ local status, result
+
+ status, result = pcall(toRPCName, name)
+ if status then
+ print(' ' .. name .. ' - ' .. result)
+ else
+ print('! ' .. name)
+ print('> ' .. result)
+ end
+end
diff --git a/docs/system/startup/startup-api.rst b/docs/system/startup/startup-api.rst
index f7000fe..2d30dbd 100644
--- a/docs/system/startup/startup-api.rst
+++ b/docs/system/startup/startup-api.rst
@@ -143,8 +143,9 @@ On Lua 5.3 if available, the following utilities are also available:
Startup components API
----------------------
-The main abstract bus is available through the ``bus`` global variable, which
-corresponds to the main abstract bus. Every device has the following variables:
+Tha main abstract bus is available through the ``bus`` global variable,
+which corresponds to the core bus. Every component, including the core bus,
+is of the following type:
.. lua:module:: startup
@@ -162,15 +163,10 @@ corresponds to the main abstract bus. Every device has the following variables:
The address of the component on the parent bus, which format depends
on the bus type.
- .. lua:attribute:: manufacturer: string
+ .. lua:attribute:: type: string
- The name of the component's manufacturer, as a string; usually
- represents the mod which brings the device, e.g. ``"computercraft"``.
-
- .. lua:attribute:: name: string
-
- The name of the component, as a string; usually represents the
- device type, e.g. ``"modem"`` or ``"computer"``.
+ The string representing the device type, e.g.
+ ``core-bus.thox.madefor.cc`` or ``modem.tweaked.cc``.
.. lua:attribute:: available: boolean