path: root/man/magi.3

.TH MAGI 3 2020-07-14 v0.0.1 "Library Manual"
.SH NAME
.B magi
\- Common Gateway Interface (CGI) library
.SH SYNOPSIS
.B #include <magi.h>
.SH DESCRIPTION
The
.B magi
library gives the user a way to interact with the web server
through CGI as described in
.IR "RFC 3875" .
The library is free and open source software.
It is written in ANSI C without any dependencies except C standard library.
.SS Usage overview
A program using
.B magi
library must be linked with the
.B -lmagi
option.
.P
Main task of the
.B magi
library is to analyse CGI request and represent it to the user in
.B magi_request
data structure.
CGI request is passed in environment variables and standard input.
You can access environment directly even then using magi,
however reading from standard input will cause a mess.
.P
The library also provides response functionality with
.B magi_response
and its methods.
Since body can be everything and only headers have specific CGI-related
structure,
.B magi
provides response functionality only for them.
Body can be outputted directly into standard output with any method you want
after forming and sending CGI headers via
.BR magi_response .
.SH REQUEST
Request structure initializtion is done with
.BR magi_request_init .
Don't forget to free everything in it then the work is done via
.BR magi_request_free .
.P
.RS
.nf
struct magi_request request;
magi_request_init(&request);
/* do your work with request */
magi_request_free(&request);
.fi
.RE
.P
Obtaining of request is done in two parts, i.e. head via
.B magi_parse_head
and body via
.BR magi_parse_body .
Analysis of head will fill everything in
.B magi_request
structure, except
.I body
and
.I files
fields.
Such separtion has place since body processing can depend on data from head,
e.g. in case of loading files, if file size is defined by user group.
If analysis succeeded they will return 1, otherwise 0 as error mark.
More disctinct error code will be placed in
.IR request.error .
.P
.RS
.nf
if (!magi_parse_head(&request)) {
    /* handle error and exit */
}
/* configure body processing using head data */
if (magi_parse_body(&request)) {
    /* send response using request data */
} else {
    /* handle error */
}
.fi
.RE
.P
If your case is not as advanced, you can use shortuct
.B magi_parse
to analyse both head and body.
.BR magi_parse (&request)
is literally
.BR magi_parse_head (&request)
&&
.BR magi_parse_body (&request).
.P
.RS
.nf
if (magi_parse(&request)) {
    /* send response using request data */
} else {
    /* handle error */
}
.fi
.RE
.SS General information in request
Request method is case-sensitive ("GET", "POST", etc.) and stored in
.I method
field.
.P
Server's document root (e.g. /var/www/htdocs) is in
.I document_root
field.  It is useful in case of processing documents on server, e.g.
if you are building CMS.
.P
If request was done over HTTPS
.I is_secure
field will be set as 1, otherwise as zero (actually it checks port to be 443,
which is standard HTTPS port).
.P
You can restore URL by following formula:
.P
.RS
.nf
http[s]://{host}:{port}{script}{path}[?...]
.fi
.RE
.P
there
.I host
(e.g. "example.com"),
.I port
(usually 80 or 443),
.I script
(e.g. "/cgi-bin/script") and
.I path
(e.g. "/login") are fields.  All that values are lowercased, since they are
case-insensitive.
.SS Form fields values in request
Parameters passed in URL after question mark (e.g. "?q=example&color=red")
are stored in linked list of key-values
.RB ( magi_params )
field
.IR head ,
while HTML form fields values passed in body (except for files,
described lower) are stored in
.IR body .
To get value of parameter by its key use
.BR magi_request_param .
This function priorities body params, so if you need specifically
parameter from URL use
.B magi_request_urlparam .
If no parameter was passed with given name, these functions will return null.
.P
For example, if we build search engine and want to access query passed in
form field with name
.IR q ,
we must call:
.P
.RS
.nf
const char *query = magi_request_param(&request, "q");
if (query) {
    /* calculate and show result */
} else {
    /* show welcoming page */
}
.fi
.RE
.P
Note what values returned by
.B magi_request_urlparam
are decoded from URL encoding, so you don't need to deal with all that
percents and pluses.  Result of
.B magi_request_param
is also raw data.
.SS Cookies in request
Same situation with cookies, stored in
.I cookies
field, and accessible via
.BR magi_request_cookie .
.P
For example, we can check session ID of user, stored in cookie "sid":
.P
.RS
.nf
struct awesome_session session;
const char *sid = magi_request_cookie(&request, "sid");
if (!sid) {
    /* render response for unauthorised user */
} else if (session_exists(sid)) {
    load_session(&session, sid);
    /* render response for this user */
} else {
    /* show error page of invalid session */
}
.fi
.RE
.P
While for cookies as described in
.I RFC 6265
it's all you need, your server can use Cookie2, as described in
.IR "RFC 2965" .
In both cases
.B magi_request_cookie
will return the most accurate cookie for this request, however Cookie2
allows more complex behavior, setting and receiving different host and path
for cookies.  You able to receive all information about cookie using
.BR magi_request_cookie_complex ,
which returns pointer to
.B magi_cookie
structure.  If no cookie is found, result is null.  It has fields
.IR name ,
.IR data ,
.I path
(without '/' at the end),
.I domain
(with dot at the begining) and
.I max_age
(the last one is used only in response).
.SS Files in request
.SH RESPONSE
.SS URL encoding
It is described in
.IR "RFC 3986" .
Briefly it is replacement of every space into plus sign and every not
alpha-numerical or not one of "~-._" character inte percent sign
followed by hexademical representation of given character byte.
.P
The
.B magi
library provides functions to form url-encoded strings, which is very useful
in forming response.  Use
.B magi_urlenc_size
to find what the size of code will be and then call
.B magi_urlenc
for encoding itself.
.P
For example, lets form URL to search in DuckDuckGo for provided char
.RI * query
in char
.RI * url .
.P
.RS
.nf
const char *prefix     = "http://duckduckgo.com/?q=";
const int   prelen     = strlen(prefix);
const int   urlencsize = magi_urlenc_size(query);
url = malloc(prelen + urlencsize + 1);
strcpy(url, prefix);
magi_urlenc(query, url + prelen);
url[prelen + urlencsize] = 0;
.fi
.RE
.P
Note that second argument of
.B magi_urlenc
which is encoding destination should be at least size of
.B magi_urlenc_size
of plain data, and that
.B magi_urlenc
doesn't write zero to form null-terminated string in its output.
.SH ERRORS
If function is returning pointer, error is only in case of null returned.
If function is returning
.I int
as success mark it will be null only in case of error, and one otherwise.
Exact
.B magi_error
code is in
.B error
field of
.B magi_request
structure.  For other modules error codes seem to be overkill.
.SH DEBUGGING
To debug your CGI scripts with
.I gdb
you can include signal.h:
.P
.RS
.nf
#include <signal.h>
.fi
.RE
.P
and stop your script in the beginning with:
.P
.RS
.nf
raise(SIGSTOP);
.fi
.RE
.P
Then compile your script and place it in directory which is handled by your
CGI server.
Check timeout settings for CGI scripts on your server and make it big enough,
since the server will kill your script by timeout.
Now make request to your server and run the following in the shell as root:
.P
.RS
.nf
gdb path_to_your_executable `pgrep name_of_your_executable`
.fi
.RE
.P
This will connect
.I gdb
to your running CGI script.  It will be paused by SIGSTOP, so you will be able
to setup your breakpoints. In order to continue run:
.P
.RS
.nf
continue
.fi
.RE
.SH COMPATIBILTY
Sine
.B magi
only uses C standard library and the C language itself it should be able
to run on every environment with them, i.e. Linux, OpenBSD, FreeBSD, macOS,
Windows, etc.
.P
The
.B magi
library should work well with any server supporting CGI, since it is
compatible with
.IR "RFC 3875" ,
i.e. Apache, nginx, Caddy, etc.
.P
The library is compatible with C++, since it avoid using typedefs for structs.
However it doesn't have 'extern "C"' in the headers, so you need to wrap your
includes with it manually or use
.B #include <magi.hpp>
which is a shortcut for include of
.I magi.h
wrapped in 'extern "C"' construct.
.SH AUTHORS AND LICENSE
Copyrigth 2019-2020
.B Aleksey Veresov
.RI < aleksey@veresov.pro >
.P
This software is provided 'as-is', without any express or implied warranty.
In no event will the authors be held liable for any damages arising from
the use of this software.
.P
Permission to use, copy, modify, and distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.