Architecture

The NPM package has a different code structure because it is compiled with webpack. To follow this page, you need to refer to the GitHub repo instead.

The /src/server.ts file is the executable file that is called when the tiddlyserver command is run. It loads the config file, preflighter, and HTTPS options, then passes them all to the initServer function in /src/server/server.ts. It also sets up an uncaughtException handler to log unhandled errors before exiting.

This means that TiddlyServer could also be implemented as part of a larger system. The initServer function returns the master instance which handles all the listeners. This can be used to close the server, and then call initServer again to create a new instance. Data folders operate independant of the this, and will maintain their state within the process, allowing the listeners to restart without affecting open data folders.

For most use cases, however, the preflighter is probably your weapon of choice, allowing you to syphon off requests to handle separately, select a different host from the tree, change the auth account and username applied to the request, and pretty much anything else. To add multiple hosts to a tree, create the following Javascript file and set the path as the tree property in your config.

exports.tree = [
  {} | [], //as many tree objects here as you want, using the hybrid syntax.
  {} | [], //as many tree objects here as you want, using the hybrid syntax.
  {} | [], //as many tree objects here as you want, using the hybrid syntax.
  {} | [], //as many tree objects here as you want, using the hybrid syntax.
];
// This tells the parser to expect an array of hosts. 
// Set this to false to parse the tree as a single host.
exports.multiple = true;

This is an interface representing the RequestEvent. It may be used as the TypeScript interface for the request event passed to the preflighter. There are a couple other properties and methods used internally which are not listed here.

export interface RequestEvent {

// if this is true after calling the preflighter, no further processing occurs

handled: boolean;

// the settings object being applied to this request

// changing this is not officially supported, but may work

settings: ServerConfig,

// the HTTP request

request: IncomingMessage,

// which type of request this is

type: "client" | "response",

// only the one specified in type will be defined

client: WebSocket;

response: ServerResponse;

// the network info for the request

network: {

// listen address passed to the HTTP Server.listen

iface: string;

// host header of the request

host: string | undefined;

// local interface address

addr: string;

};

// returns the permissions object that applies based

// on authAccountKey and localAddressPermissionsKey

allow: ServerConfig_AccessOptions;

//getter that returns the treeHost at treeHostIndex

hostRoot: Config.HostElement;

// username for this request, preset if logged in

username: string;

// authAccounts object key that applies to this request

authAccountKey: string;

// bindInfo.localAddressPermissions object key that applies to this request

localAddressPermissionsKey: string;

// the host index in the tree

treeHostIndex: number;

// the output stream of the debug logger, may be changed or used by the preflighter

debugOutput: Writable;

// resolves the url to determine the tree node this request applies to

resolvePath(): PathResolverResult | undefined;

// close the response or client with this code and message

close(code: number, message?: string | undefined): void;

// get the tree options (auth, index, and putsaver) that apply to this tree node

getTreeOptions(result: PathResolverResult): OptionsConfig;

}