vpp/docs/usecases/webapp.rst
Nathan Skrzypczak 9ad39c026c docs: better docs, mv doxygen to sphinx
This patch refactors the VPP sphinx docs
in order to make it easier to consume
for external readers as well as VPP developers.

It also makes sphinx the single source
of documentation, which simplifies maintenance
and operation.

Most important updates are:

- reformat the existing documentation as rst
- split RELEASE.md and move it into separate rst files
- remove section 'events'
- remove section 'archive'
- remove section 'related projects'
- remove section 'feature by release'
- remove section 'Various links'
- make (Configuration reference, CLI docs,
  developer docs) top level items in the list
- move 'Use Cases' as part of 'About VPP'
- move 'Troubleshooting' as part of 'Getting Started'
- move test framework docs into 'Developer Documentation'
- add a 'Contributing' section for gerrit,
  docs and other contributer related infos
- deprecate doxygen and test-docs targets
- redirect the "make doxygen" target to "make docs"

Type: refactor

Change-Id: I552a5645d5b7964d547f99b1336e2ac24e7c209f
Signed-off-by: Nathan Skrzypczak <nathan.skrzypczak@gmail.com>
Signed-off-by: Andrew Yourtchenko <ayourtch@gmail.com>
2021-10-13 23:22:32 +00:00

280 lines
8.6 KiB
ReStructuredText
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Web applications with VPP
=========================
Vpp includes a versatile http/https “static” server plugin. We quote the
word static in the previous sentence because the server is easily
extended. This note describes how to build a Hugo site which includes
both monitoring and control functions.
Lets assume that we have a vpp data-plane plugin which needs a
monitoring and control web application. Heres how to build one.
Step 1: Add URL handlers
------------------------
Individual URL handlers are pretty straightforward. You can return just
about anything you like, but as we work through the example youll see
why returning data in .json format tends to work out pretty well.
::
static int
handle_get_status (http_builtin_method_type_t reqtype,
u8 * request, http_session_t * hs)
{
my_main_t *mm = &my_main;
u8 *s = 0;
/* Construct a .json reply */
s = format (s, "{\"status\": {");
s = format (s, " \"thing1\": \"%s\",", mm->thing1_value_string);
s = format (s, " \"thing2\": \"%s\",", mm->thing2_value_string);
/* ... etc ... */
s = format (s, " \"lastthing\": \"%s\"", mm->last_value_string);
s = format (s, "}}");
/* And tell the static server plugin how to send the results */
hs->data = s;
hs->data_offset = 0;
hs->cache_pool_index = ~0;
hs->free_data = 1; /* free s when done with it, in the framework */
return 0;
}
Words to the Wise: Chrome has a very nice set of debugging tools. Select
“More Tools -> Developer Tools”. Right-hand sidebar appears with html
source code, a javascript debugger, network results including .json
objects, and so on.
Note: .json object format is **intolerant** of both missing and extra
commas, missing and extra curly-braces. Its easy to waste a
considerable amount of time debugging .json bugs.
Step 2: Register URL handlers with the server
---------------------------------------------
Call http_static_server_register_builtin_handler() as shown. Its likely
but not guaranteed that the static server plugin will be available.
::
int
plugin_url_init (vlib_main_t * vm)
{
void (*fp) (void *, char *, int);
/* Look up the builtin URL registration handler */
fp = vlib_get_plugin_symbol ("http_static_plugin.so",
"http_static_server_register_builtin_handler");
if (fp == 0)
{
clib_warning ("http_static_plugin.so not loaded...");
return -1;
}
(*fp) (handle_get_status, "status.json", HTTP_BUILTIN_METHOD_GET);
(*fp) (handle_get_run, "run.json", HTTP_BUILTIN_METHOD_GET);
(*fp) (handle_get_reset, "reset.json", HTTP_BUILTIN_METHOD_GET);
(*fp) (handle_get_stop, "stop.json", HTTP_BUILTIN_METHOD_GET);
return 0;
}
Make sure to start the http static server **before** calling
plugin_url_init(…), or the registrations will disappear.
Step 3: Install Hugo, pick a theme, and create a site
-----------------------------------------------------
Please refer to the Hugo documentation.
See `the Hugo Quick Start
Page <https://gohugo.io/getting-started/quick-start>`__. Prebuilt binary
artifacts for many different environments are available on `the Hugo
release page <https://github.com/gohugoio/hugo/releases>`__.
To pick a theme, visit `the Hugo Theme
site <https://themes.gohugo.io>`__. Decide what you need your site to
look like. Stay away from complex themes unless youre prepared to spend
considerable time tweaking and tuning.
The “Introduction” theme is a good choice for a simple site, YMMV.
Step 4: Create a “rawhtml” shortcode
------------------------------------
Once youve initialized your new site, create the directory
/layouts/shortcodes. Create the file “rawhtml.html” in that directory,
with the following contents:
::
<!-- raw html -->
{{.Inner}}
This is a key trick which allows a static Hugo site to include
javascript code.
Step 5: create Hugo content which interacts with vpp
----------------------------------------------------
Now its time to do some web front-end coding in javascript. Of course,
you can create static text, images, etc. as described in the Hugo
documentation. Nothing changes in that respect.
To include dynamically-generated data in your Hugo pages, splat down
some
.. raw:: html
<div>
HTML tags, and define a few buttons:
::
{{< rawhtml >}}
<div id="Thing1"></div>
<div id="Thing2"></div>
<div id="Lastthing"></div>
<input type="button" value="Run" onclick="runButtonClick()">
<input type="button" value="Reset" onclick="resetButtonClick()">
<input type="button" value="Stop" onclick="stopButtonClick()">
<div id="Message"></div>
{{< /rawhtml >}}
Time for some javascript code to interact with vpp:
::
{{< rawhtml >}}
<script>
async function getStatusJson() {
pump_url = location.href + "status.json";
const json = await fetch(pump_url, {
method: 'GET',
mode: 'no-cors',
cache: 'no-cache',
headers: {
'Content-Type': 'application/json',
},
})
.then((response) => response.json())
.catch(function(error) {
console.log(error);
});
return json.status;
};
async function sendButton(which) {
my_url = location.href + which + ".json";
const json = await fetch(my_url, {
method: 'GET',
mode: 'no-cors',
cache: 'no-cache',
headers: {
'Content-Type': 'application/json',
},
})
.then((response) => response.json())
.catch(function(error) {
console.log(error);
});
return json.message;
};
async function getStatus() {
const status = await getStatusJson();
document.getElementById("Thing1").innerHTML = status.thing1;
document.getElementById("Thing2").innerHTML = status.thing2;
document.getElementById("Lastthing").innerHTML = status.lastthing;
};
async function runButtonClick() {
const json = await sendButton("run");
document.getElementById("Message").innerHTML = json.Message;
}
async function resetButtonClick() {
const json = await sendButton("reset");
document.getElementById("Message").innerHTML = json.Message;
}
async function stopButtonClick() {
const json = await sendButton("stop");
document.getElementById("Message").innerHTML = json.Message;
}
getStatus();
</script>
{{< /rawhtml >}}
At this level, javascript coding is pretty simple. Unless you know
exactly what youre doing, please follow the async function / await
pattern shown above.
Step 6: compile the website
---------------------------
At the top of the website workspace, simply type “hugo”. The compiled
website lands in the “public” subdirectory.
You can use the Hugo static server - with suitable stub javascript code
- to see what your site will eventually look like. To start the hugo
static server, type “hugo server”. Browse to “http://localhost:1313”.
Step 7: configure vpp
---------------------
In terms of command-line args: you may wish to use poll-sleep-usec 100
to keep the load average low. Totally appropriate if vpp wont be
processing a lot of packets or handling high-rate http/https traffic.
::
unix {
...
poll-sleep-usec 100
startup-config ... see below ...
...
}
If you wish to provide an https site, configure tls. The simplest tls
configuration uses a built-in test certificate - which will annoy Chrome
/ Firefox - but its sufficient for testing:
::
tls {
use-test-cert-in-ca
}
vpp startup configuration
~~~~~~~~~~~~~~~~~~~~~~~~~
Enable the vpp static server by way of the startup config mentioned
above:
::
http static server www-root /myhugosite/public uri tcp://0.0.0.0/2345 cache-size 5m fifo-size 8192
The www-root must be specified, and must correctly name the compiled
hugo site root. If your Hugo site is located at /myhugosite, specify
“www-root /myhugosite/public” in the “http static server” stanza. The
uri shown above binds to TCP port 2345.
If youre using https, use a uri like “tls://0.0.0.0/443” instead of the
uri shown above.
You may want to add a Linux host interface to view the full-up site
locally:
::
create tap host-if-name lstack host-ip4-addr 192.168.10.2/24
set int ip address tap0 192.168.10.1/24
set int state tap0 up