information system development
About About
Products Products
Articles Articles
Contacts Contacts
Russian Russian


State Machine

Machine for controle of states and environment of web-server

Download (

1. Brief description.

State Machine (further is SM) was developed to overcome the main, in our opinion, obstacle arising with the development of complex web-applications, namely the absence of a user context available all the time (at least for the period of a session). As a result:

  • it is impossible to create a program in a form of a usual (for programmers and users) tree of calls of "procedure call - return" (or, from user's point of view, for example, "dialog window appearence - return");
  • or it's necessary that the execution context should be "handed over" from a form to another and so on; all this is awful when being realized and results in disturbance of secrecy and integrity of the application;
  • it's necessary to save the execution context in some format in server (e.g. in database) and to restore it during the next all.

Actually, SM realizes the last variant, but does it in a way which is"clear" to the application. In other words, cgi application sees no control SM directives. It's seen from its name, that SM is intended for controlling states of the application. State implies a set of cgi process environment vaiables, which is associated with its name (by run) and arguments. SM is located between web-server and cgi program, and it directs server stream and environment variable to the program and filtrates output stream of cgi program (only for Content-type: text/html). In case of detecting directive variables (forSM), SM executes certain actions on controlling states (saving and subsequent recovery, generation of new states, and return to parent ones), and also replace a part of URL in output stream, modifying them for further use. Thus, SM forms a tree of states, which, in fact, create an integral application of separate cgi programs.

Now, SM has been realized in a form of two programs - smconn and sm. Web server always calls smconn and gives it the rest of the path.

For example, application input point can be in the form:


and "inside" the application it will something like:


In its turn, smconn is connected via Unix-domain-socket, "at the other end" of which sm proper is "located". In case of a call detected, sm runs sepatate thread for serving this call, and then necessary cgi program is started in sm.

Thus, at least two processes are started for processing of each call: smconn and cgi program proper. Although smconn is quite small and practically doesn't consumes system resourses, its run can be avoided, if module to web-server, performing its functions, is used.

As it's seen, the given scheme isn't quite simple, and the question arises: why couldn't SM function be realized directly in module of web- server? Unfortunately, in it's impossible. In its semantics, a SINGLE sm must process ALL calls to a specific application. Standard web-servers - for example, apache - create a set of copies of themselves to optimize processing calls, and, though this process can be controled within some limits, there's no full control.

The first version of SM was based on of knon protocol - FastCGI, but it turned out, that "reproduction" of server processes "reproducts" executors, which is inadmissible. Besides, FastCGI realization (free), that we have, has proved to be rather complex and unstable...

2. Control directives SM.

All control directives recognized by SM are described in a form of HTML tags, or rather in a form of HTML-comments. This, to some extent, makes SM extension easier - unrecognized directives will not litter user interface.
Also, when describing directives, parts enclosed in square brackets [ ] are not obligatory.

2.1. Call directive call.

<!#call program="progname" [return="retname"] [prefix="url_prefix"] [src="url_src"]>
<!#fcall program="progname" [return="retname"] [prefix="url_prefix"]>

When used out of forms, call tag is replaced for <a href=state&34234234>, new (empty) space being created, i.e. some blank of state, containing only cgi-program name and its arguments.

For example, if in input stream there's:
<!#fcall program=" main_context">Help</a>
then user will have something like
<a href="state&4234234&call">Help</a>

and, with the activation of this reference,SM activates corresponding state as a child state in relation to current one and will run program c with the argument of main_context command line. It should be noted that standard semantics of cgi-calls doesn't allow to transfer command line arguments, and this is quite inconvenient sometimes.

Return attribute defines the name of environment variable in which the result will put (see <!#return>).

If prefix attribute is, its value is added before href value. Sometimes this is necessary for manual control of states - to replace, for example, a current (relative to webserver) directory, or to change acess or recoding rights.

When used in forms, <!#call ...>directive is replaced for <input type=submit ...> or, if src attrbute has been transferred, for <input type=image ...>, url_srcattribute is source URL of image.

For example,
<!#call program="" value="forward" size=20>

call directive will be replaced for
<input type=hidden name=_C_1 value="_N_1">
<input type=submit name="_N_1" value="forward" size="20">

or, with use of src:
attribute <!#form>
<!#call program="" value="forward" size=20 src="forward.gif">
call directive will be replaced for
<input type=hidden name=_C_1 value="_N_1">
<input type=image name="_N_1" value="forward" size="20" src="/images/imail/forward.gif">

src attribute <input type=image ...>tag takes the valie of imagedir attribute of SM cinfiguration file plus плюс the value of src attribute of <!#call ...> control directive.

imagedir directive of SMconfiguration file (sm.cfg) in this example takes /images/imailvalue. See also <!#form> and directives of SMconfiguration file (sm.cfg) imagedir

2.2. scalldirective.

<!#scall program="program_scall">

Directive is used in JavaScriptprograms to create states.
Foe example:
<script language="JavaScript">
..., ...); ...
in output stream will be:
<script language="JavaScript">
..."state&121212&scall", ...); ...
where 121212 is sttae number.

2.3. returnreturn.

<!#return [return="retval"] [statename="state_name"] [href="localref"] [query="query"] [prefix="url_prefix"]>

return in input stream is replaced for a reference returning to parent state; for example, if the parent state has number 1234, then <!#return>back</a>
will be replaced for
<a href="state&1234&return">back </a>.

return attribute sets the value returned in parent state. This value will be assigned to environment variable indicated in calldirective.
For example, ...
<!#call program="" return="asdf">
<!#return return="0">

asdf environment value, after executing cgii program -, will be assigned with 0value. If statenameattribute has been set, then the retun is performed to the state having "state_name" name (see <!#statename>).

If hrefattribute is set, its value is added (after # ) to resulting URL (i.e. as a reference inside a page). queryvalue is added to resulting URL after "?". prefix is used in the same may as in <! #call ...>. With the return to any state, all child states are destroyed automatically.

2.4. State name setting statename

<!#statename "some_name">

Any newly created state is automatiacally assigned with a unique name. statenamedirective allows the state to be assigned with some_namename.
Later, this name can be used to return to the state from child states.
For example,
<!#statename "my_state">
<!#call program="">
<!#return statename="my_state">
(см. <!#return>).

2.5. Creating variables.

Program executed underSM can determine for itself (and for child states) environment variables and assign variables to them. Variables can have localvisibility scope - public, private and global, and they are created by control directive in the form of :

<!#local   name1=value1 ... nameN=valueN>
<!#private name1=value1 ... nameN=valueN>
<!#public  name1=value1 ... nameN=valueN>
<!#global  name1=value1 ... nameN=valueN>

local variables belong only to the state in which they have been created.

private variables belong to the state in which they have been created, but are transferred to child states. A child state can change privatevariable of a partent, as private will create a new variable shadowing a parent variable.

public variables are inherited by child states. Thus, if the child state assigns a value to public variable, then publicparent variable changes as well.

global are publicvariables belongning to the highest (root) state. If several variables have one and the same name, the priory is given to local, then to private and to public.

Remark: environment variables common to the whole application may be можно determined by envar directive of SMconfiguration file sm.cfg.

2.6. Creation of forms form

<!#form ... >... </form>

<!#form ... > understands the same attributes as <form>standard tag does.
For example, if in input stream there is:
<!#form target="asdf">...</form>,
then user receives something like
<form action=state&12345&form target="asdf">,
where 12345 is current state number. In form, to create submit buttons, calldirective may be used. In this case, control will be given to cgi-program set by programattribute of <!#call ...> directive. But use of standard tags isn't prohibited:

<input type=submit ...> и <input type=image ...>.
In the last case, controll will be given into the same form.

2.7. Creating images.

<!#img src="url_src" ...>
<!#limg src="url_src" ...>

Directives understand attributes which are standard for <img>tag. In output stream we have:
<img src="dir_for_image/url_src">
<img src="dir_for_image/kod_language/url_src"> for <!#limg ...> directive.
url_src - URL of image.
dir_for_image is set by sm.cfg imagedirconfiguration fale directive
kod_language is a two-letter abraviation of language used by browser to display of page contents. This language is set by browser preferences.

2.8. Directive bind.

<!#bind cid="content_ID" program="bind_program [param1 ...]">
It binds resource identifier to cgi-программой, bind_program, of this resourse processing.

2.9. Directive expire.

<!#expire timeout=timeout_sec>

It sets timeout_sec period in seconds, upon the expiry of which SM state is destroyed.

2.10. Directive clearquery.


It clears QUERY_STRINGenvironment varoable.

2.11. Directive option.

<!#option strict=on|yes|off|no>

It determines processing method of hrefattribute of <A> tag.
strict=on|yes is a "hard" processing of hrefattribute, i.e., if in cgi-program
<a href="">Call </a>,
then in output stream:
<a href="">Call </a>

If strict=off|no is a method by default, then in output stream:
<a href="state&12345&call">Call & #60;/a>
And to name, work_dir_namewill be added, i.e. working directory.

2.12. Print derective print.

<!#print program="program_name">
<!#print on|off>

programattribute determines cgi print program. It is replaced for hyperreference tag and requires a closing tag.

on allows output for printing, and off prohibits this.
For example,
<!#print program="program_name"> Document print </a >
will be replaced for
<a href="state&1234&print" > Document prind </a>
cgi-program in STDIN the stream is transferred - current page of stream.

2.13. Directive quit.


It destroys all SM states and, after the complition, executes cgi-program with quitname.

3. Configuration file directives SM sm.cfg


3.1 debuglevel

Syntax: debuglevel <numberlevel>

It sets the level of output of massages to log-file.

  • 0 - minimal (error massages only)
  • 1 - stands by default (start/stop, call receipt, application start)
  • 3 - applicable for debugging
  • 9 - maximal

3.2 end-of-request

end-of-request <eor-string>

It sets a string used for indicating call end during dialog with servers.
For example:
end_of_request "<<<EOR>>>"

3.3. pidname

pidname <file-with-pid-name>

It sets file name in which pid of SM
process is stored. For example:
pidname ./spool/

3.4. logname

logname <log-file-name>

It sets log-file name. Its contents are dependent of debugleveldirective. Also, this file has all information about errors SM, start and stop of state machine.
For example,
logname ./spool/sm.log

3.5. server

server <"pipe"|"pty"|"socket"> <name><executable-name >[<arg1>... <argN>]

executable-name program processes calls sent by SM cgi-programs.
pipe|pty|socket set typy of program communication with SM.
name - processing program name, known to state machine, arg1, ..., argN are parameters accepted by it.
For example,
server pipe cgi ./progs/cgiutil
server pipe users ./progs/dbmutil spool/users

3.6. envar

envar <name><value>

It sets an environment variable common to the whole application.
For example,
envar FORTUNE "/usr/games/fortune"

3.7. allow

allow <executable-name-1>[ ...<executable-name-N>]

It determines names - executable-name-1[ ...executable-name-N] - as allowed points of entrance into application.
For example,
allow init
init program is the only entarnce point:

3.8. header

header <header-string>

HTTP string of response header.

3.9. workdir

workdir <work-dir-name>

Working directory of cgi-programs
For example,
workdir /usr/program/cgi-bin/mail/progs

3.10. fdlimit

fdlimit <number>

It sets maximal quantity of open file descriptors. If their quantity exceeds number, this doesn't allow to open new ones.

3.11. expire

expire <minuts>

It sets minuts time in minutes after the expiry of which SM state is destroyed. This value is taken by default, if resource URL contains no href=#expire>expire control directive.

3.12. locale

locale <locale-name> <locale-file>

It sets path for massage files.

SM checks browser preferences - current browse language - and, using message file, replaces all strings enclosed in _(message text)_ for strings corresponding to established browse language. For example, if in cgi-program there is _(Press any key to continue...)_ then in output stream, depending on settings, there will be en Press any key to continue... ru Для продолжения работы нажмите любую клавишу...

3.13. imagedir

imagedir <dir-for-images>

It sets a directory for images.
For example,
imagedir /images/imail

© Engineering & Technical company LTD (E&T co. LTD) 2006
426072, Udmurtia, Izhevsk p/b 1247, uri at itk dot ru