Skip to content

Commit 4fca23f

Browse files
pirannapiranna
authored
Merge pull request #6 from luii/documentation
Documentation
2 parents b70864c + 9fba160 commit 4fca23f

1 file changed

Lines changed: 174 additions & 3 deletions

File tree

‎server.js‎

Lines changed: 174 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,18 @@ var cmdline
2828
var ROOT_HOME = ''
2929
var single
3030

31-
31+
/**
32+
* This callback is part of the `mountDevProcTmp_ExecInit` function
33+
* @callback mountDevProcCallback
34+
* @param {Error} error The callback is called with a error if the devices
35+
* couldnt be mounted
36+
*/
37+
38+
/**
39+
* This error handler traces the error and starts a node.js repl
40+
* @access private
41+
* @param {Error} error The error that gets traced
42+
*/
3243
function onerror(error)
3344
{
3445
if(error)
@@ -39,6 +50,26 @@ function onerror(error)
3950
}
4051
}
4152

53+
/**
54+
* This functions takes the `cmdline` from `/proc/cmdline` **showed below in
55+
* the example** and splits it into key/value pairs
56+
* @access private
57+
* @param {String} cmdline This string contains information about the
58+
* initrd and the root partition
59+
* @return {Object} It returns a object containing key/value pairs
60+
* if there is no value for the key then its just true.
61+
* **For more Information, look at the example**
62+
* @example
63+
* var cmdline1 = 'initrd=\\initramfs-linux.img root=PARTUUID=someuuidhere\n'
64+
* var cmdline2 = 'somevar root=PARTUUID=someuuidhere\n'
65+
*
66+
* var res1 = linuxCmdline(cmdline1)
67+
* var res2 = linuxCmdline(cmdline2)
68+
* console.log(res1)
69+
* //-> { initrd: '\\initramfs-linux.img',root: 'PARTUUID=someuuidhere' }
70+
* console.log(res2)
71+
* //-> { somevar: true, root: 'PARTUUID=someuuidhere' }
72+
*/
4273
function linuxCmdline(cmdline)
4374
{
4475
var result = {}
@@ -62,19 +93,67 @@ function linuxCmdline(cmdline)
6293
return result
6394
}
6495

65-
96+
/**
97+
* This functions mounts the provided path to the device.
98+
* **If no device is available then it uses the type**
99+
* @access private
100+
* @param {Object} info This object holds information
101+
* about the folder to create
102+
* @property {String} info.dev Device-File being mounted
103+
* (located in `/dev`) a.k.a. devFile.
104+
* @property {String} info.path Directory to mount the device to.
105+
* @property {String} info.type Filesystem identificator
106+
* (one of `/proc/filesystems`).
107+
* @property {Array|Number} info.[flags] Flags for mounting
108+
* @property {String} info.[extras] The data argument is
109+
* interpreted by the different
110+
* file systems. Typically it is a
111+
* string of comma-separated options
112+
* understood by this file system.
113+
* @param {Function} callback Function called after the
114+
* mount operation finishes.
115+
* Receives only one argument err.
116+
*/
66117
function mkdirMountInfo(info, callback)
67118
{
68119
var dev = info.dev || info.type
69120

70121
utils.mkdirMount(dev, info.path, info.type, info.flags, info.extras, callback)
71122
}
72123

124+
/**
125+
* Asynchronously create a target directory mount the source with `MS_MOVE` to it
126+
* and move all files to the newly created directory
127+
* @access private
128+
* @param {Object} info
129+
* @property {String} info.source The source subtree to move
130+
* @property {String} info.target The path to move the subtree into
131+
* @param {Function} callback The callback gets called if the move
132+
* operations is done
133+
*/
73134
function mkdirMoveInfo(info, callback)
74135
{
75136
utils.mkdirMove(info.source, info.target, callback)
76137
}
77138

139+
/**
140+
* Mounts the user filesystems
141+
* @access private
142+
* @param {Array} arr A array containing objects with
143+
* the mounting information **For more Information
144+
* see mkdirMountInfo**
145+
* @param {String} upperdir Path to the Init file
146+
* The path must contain a init file
147+
* Because execInit checks the gid & uid of the file
148+
* and of the "upperdir"
149+
* @example
150+
* let infos = [ mountInfo1, mountInfo2 ] // see under mkdirMountInfo
151+
* // for more Info
152+
*
153+
* // Its necessary to exclude the init file from the path because
154+
* // mountUserFilesystems does that for you
155+
* mountUserFilesystems(infos, 'path/to/initfile', callback)
156+
*/
78157
function mountUserFilesystems(arr, upperdir, callback)
79158
{
80159
each(arr, mkdirMountInfo, function(error)
@@ -93,6 +172,15 @@ function mountUserFilesystems(arr, upperdir, callback)
93172
})
94173
}
95174

175+
/**
176+
* Waits until dev is mounted and then executes `mountUserFilesystems` to
177+
* mount `${upperdir}/proc` and `${upperdir}/tmp`
178+
* @access private
179+
* @param {String} upperdir The upperdir
180+
* @param {Boolean} isRoot True if user is root, false if not
181+
* @param {Function} callback The callback function
182+
* @return {mountDevProcCallback} Returns the callback function
183+
*/
96184
function mountDevProcTmp_ExecInit(upperdir, isRoot, callback)
97185
{
98186
var arr =
@@ -150,6 +238,15 @@ function mountDevProcTmp_ExecInit(upperdir, isRoot, callback)
150238
mountUserFilesystems(arr, upperdir, callback)
151239
}
152240

241+
/**
242+
* `overlay_user` first creates the workdir (with `0100` permission)
243+
* which is a string out of the folder where all users are located, a
244+
* constant `.workdirs` and the username e.g. `${usersFolder}/.workdirs/${user}`
245+
* @access private
246+
* @param {String} usersFolder The folder where all user folders are
247+
* @param {String} user The name of the user
248+
* @param {Function} callback The callback function
249+
*/
153250
function overlay_user(usersFolder, user, callback)
154251
{
155252
var upperdir = usersFolder+'/'+user
@@ -207,17 +304,32 @@ function overlay_user(usersFolder, user, callback)
207304
})
208305
}
209306

307+
/**
308+
* Filter folders that are valid user `$HOME`
309+
* @access private
310+
* @param {String} user The name of the user
311+
* @return {Boolean} Returns true If the first char is not a dot
312+
* and not `root` and not ´lost+found´
313+
*/
210314
function filterUser(user)
211315
{
212316
return user[0] !== '.' && user !== 'root' && user !== 'lost+found'
213317
}
214318

319+
/**
320+
* Mount users directories and exec their `init` files
321+
* @access private
322+
* @param {String} usersFolder The path to all user directories
323+
* @param {Function} callback The callback function
324+
* @return {Function} Returns the callback either with a error
325+
* or with null if everything was fine
326+
*/
215327
function overlay_users(usersFolder, callback)
216328
{
217329
function done(error)
218330
{
219331
// Remove the modules from initramfs to free memory
220-
// rimraf('/lib/node_modules')
332+
// rimraf('/lib/node_modules')
221333
rimraf('/lib/node_modules/nodeos-mount-utils')
222334

223335
// Make '/usr' a opaque folder (OverlayFS feature)
@@ -237,6 +349,15 @@ function overlay_users(usersFolder, callback)
237349
})
238350
}
239351

352+
/**
353+
* This helper waits with a limit of tries until the path exists
354+
* @access private
355+
* @param {String} path The path to check for
356+
* @param {Number} tries A limit of tries
357+
* @param {Function} callback The callback function
358+
* @return {Function} Returns the callback with either nothing
359+
* or with a error
360+
*/
240361
function waitUntilExists(path, tries, callback)
241362
{
242363
fs.exists(path, function(exists)
@@ -249,6 +370,15 @@ function waitUntilExists(path, tries, callback)
249370
})
250371
}
251372

373+
/**
374+
* This helper waits with a limit of tries until the device is mounted
375+
* @access private
376+
* @param {String} path The path to read the files from
377+
* @param {Number} tries A limit of tries
378+
* @param {Function} callback The callback function
379+
* @return {Function} Returns the callback with either a error
380+
* or nothing (if the amount of files is bigger 1)
381+
*/
252382
function waitUntilDevMounted(path, tries, callback)
253383
{
254384
fs.readdir(path, function(error, files)
@@ -263,6 +393,14 @@ function waitUntilDevMounted(path, tries, callback)
263393
})
264394
}
265395

396+
/**
397+
* A callback function for the askLocation function
398+
* @access private
399+
* @param {Error} error If the error is null it not gets printed
400+
* @param {Object} result A object containing a key for the path to the userfs
401+
* @return {Function} Returns either a prompt or a error if the mount
402+
* process fails
403+
*/
266404
function pathToUserfs(error, result)
267405
{
268406
if(error) console.warn(error)
@@ -271,6 +409,11 @@ function pathToUserfs(error, result)
271409
return mountUsersFS(cmdline)
272410
}
273411

412+
/**
413+
* Starts a prompt and asks for the location of the userfs
414+
* @access private
415+
* @param {Error} error The error will be printed in the console
416+
*/
274417
function askLocation(error)
275418
{
276419
console.warn('Could not find userfs:', error)
@@ -279,6 +422,12 @@ function askLocation(error)
279422
prompt.get('path to userfs', pathToUserfs)
280423
}
281424

425+
/**
426+
* If the `single` key is set in the cmdline it starts a admin repl
427+
* If not it just overlays the users filesystem
428+
* @access private
429+
* @param {String} home The path to folder of the users
430+
*/
282431
function adminOrUsers(home)
283432
{
284433
// Enter administrator mode
@@ -288,6 +437,15 @@ function adminOrUsers(home)
288437
overlay_users(home, onerror)
289438
}
290439

440+
/**
441+
* Prepares the session and checks if the users filesystem has a root account,
442+
* if not check if `/proc/cmdline` has the single key
443+
* It deletes the `root`, `rootfstype` and `vga` environment variables
444+
* and adds `NODE_PATH` to it.
445+
* @access private
446+
* @return {Repl} Returns either a repl or a error if the error contains
447+
* a `ENOENT` code
448+
*/
291449
function prepareSessions()
292450
{
293451
// Update environment variables
@@ -318,6 +476,19 @@ function prepareSessions()
318476
})
319477
}
320478

479+
/**
480+
* This function mounts the userfs
481+
* if the root env variable contains `container` it prepares the session
482+
* and if there is no root env var then it awaits the user device and
483+
* then mounts the user device and then prepares the session
484+
* @access private
485+
* @param {Object} cmdline This objects holds key/value pairs from the
486+
* `/proc/cmdline` file
487+
* @return {Prompt|Error} It returns either a prompt if the
488+
* tries has reached its limit or a error
489+
* if the `mkdirMount` fails to create the user
490+
* device
491+
*/
321492
function mountUsersFS(cmdline)
322493
{
323494
var usersDev = process.env.root

0 commit comments

Comments
 (0)