ksgi

1
.\"	$Id$
2
.\"
3
.\" Copyright (c) 2015, 2020 Kristaps Dzonsons <kristaps@bsd.lv>
4
.\"
5
.\" Permission to use, copy, modify, and distribute this software for any
6
.\" purpose with or without fee is hereby granted, provided that the above
7
.\" copyright notice and this permission notice appear in all copies.
8
.\"
9
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16
.\"
17
.Dd $Mdocdate$
18
.Dt KCGIREGRESS 3
19
.Os
20
.Sh NAME
21
.Nm kcgiregress ,
22
.Nm kcgi_regress_cgi ,
23
.Nm kcgi_regress_fcgi
24
.Nd regression framework for kcgi
25
.Sh LIBRARY
26
.Lb libkcgiregress
27
.Sh SYNOPSIS
28
.In kcgiregress.h
29
.Ft int
30
.Fo kcgi_regress_cgi
31
.Fa "int (*client)(void *)"
32
.Fa "void *clientData"
33
.Fa "int (*server)(void *)"
34
.Fa "void *serverData"
35
.Fc
36
.Ft int
37
.Fo kcgi_regress_fcgi
38
.Fa "int (*client)(void *)"
39
.Fa "void *clientData"
40
.Fa "int (*server)(void *)"
41
.Fa "void *serverData"
42
.Fc
43
.Sh DESCRIPTION
44
Automated testing platform for
45
.Xr kcgi 3 .
46
Allow for emulated CGI or FastCGI environments over a local network
47
port.
48
.Pp
49
The
50
.Fa server
51
callback is invoked with argument
52
.Fa serverArg
53
within a CGI or FastCGI environment as if it were spawned by a web
54
server, upon which the usual
55
.Xr khttp_parse 3
56
or
57
.Xr khttp_fcgi_init 3
58
and
59
.Xr khttp_fcgi_parse 3
60
functions are usually used to test behaviour.
61
The
62
.Fa client
63
callback communicates with the server over port 17123.
64
Usually this is orchestrated with
65
.Xr libcurl 3 .
66
The port number is fixed.
67
.Pp
68
Both of these callbacks must return zero on failure, non-zero on
69
success.
70
.Pp
71
To compile and link, use
72
.Xr pkg-config 1
73
as follows:
74
.Bd -literal -offset indent
75
% cc `pkg-config --cflags kcgi-regress` -c -o sample.o sample.c
76
% cc -o sample sample.o `pkg-config --libs kcgi-regress`
77
.Ed
78
.Pp
79
.Xr kcgi 3
80
components should use their respective
81
.Xr pkg-config 1
82
identifiers, such as
83
.Qq kcgi-json
84
for
85
.Xr kcgijson 3
86
output.
87
Applications using
88
.Xr libcurl 3
89
should further use
90
.Xr curl-config 1
91
as well, or on some systems,
92
.Xr pkg-config 1
93
with
94
.Qq libcurl .
95
.Sh RETURN VALUES
96
These functions return zero on failure, non-zero on success.
97
.Sh EXAMPLES
98
The following regression test simply checks that the server responds.
99
Its only check is for operation and HTTP status code (201).
100
.Bd -literal -offset indent
101
#include <stdarg.h>
102
#include <stdint.h>
103
#include <stdlib.h>
104
#include <curl/curl.h>
105
#include <kcgi.h>
106
#include <kcgijson.h>
107
#include <kcgiregress.h>
108

109
static int
110
server(void *arg)
111
{
112
  struct kreq      r;
113

114
  if (khttp_parse(&r, NULL, 0, NULL, 0, 0) != KCGI_OK)
115
    return 0;
116
  khttp_head(&r, kresps[KRESP_STATUS],
117
    "%s", khttps[KHTTP_201]);
118
  khttp_head(&r, kresps[KRESP_CONTENT_TYPE],
119
    "%s", kmimetypes[KMIME_APP_JSON]);
120
  khttp_body(&r);
121
  khttp_free(&r);
122

123
  return 1;
124
}
125

126
static int
127
client(void *arg)
128
{
129
  CURL    *curl;
130
  long     http;
131

132
  if ((curl = curl_easy_init()) == NULL)
133
    return 0;
134
  curl_easy_setopt(curl, CURLOPT_URL,
135
    "http://localhost:17123/index.json");
136
  if (curl_easy_perform(curl) != CURLE_OK)
137
    return 0;
138
  curl_easy_getinfo(curl, CURLINFO_RESPONSE_CODE, &http);
139
  curl_easy_cleanup(curl);
140
  curl_global_cleanup();
141

142
  return http == 201;
143
}
144

145
int
146
main(void)
147
{
148
  return kcgi_regress_cgi
149
    (client, NULL, server, NULL) ? 0 : 1;
150
}
151
.Ed
152
.Pp
153
To compile this simple regression test, the
154
.Xr kcgi 3 ,
155
.Xr kcgiregress 3 ,
156
.Xr kcgijson 3 ,
157
and
158
.Xr libcurl 3
159
libraries and headers are needed, along with further dependencies.
160
Let the file be named
161
.Pa sample.c .
162
.Bd -literal -offset indent
163
% export PKGS="kcgi-regress kcgi-json libcurl"
164
% cc `pkg-config --cflags $PKGS` -c sample.c
165
% cc -o sample sample.o `pkg-config --libs $PKGS`
166
.Ed
167
.Pp
168
This assumes that
169
.Xr libcurl 3
170
has its configuration recognised by
171
.Xr pkg-config 1 ,
172
which isn't always the case: sometimes
173
.Xr curl-config 1
174
is required.
175
.Sh AUTHORS
176
Written by
177
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
178