You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by am...@apache.org on 2013/07/30 22:16:21 UTC
git commit: Documentation: fixes for blacklist plugin example (format
& code)
Updated Branches:
refs/heads/master 055fa203d -> 7c1c7fdb2
Documentation: fixes for blacklist plugin example (format & code)
Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/7c1c7fdb
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/7c1c7fdb
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/7c1c7fdb
Branch: refs/heads/master
Commit: 7c1c7fdb2c52ba7461cfbcd6876ff83cf46e86b2
Parents: 055fa20
Author: Alan M. Carroll <am...@network-geographics.com>
Authored: Tue Jul 30 15:15:58 2013 -0500
Committer: Alan M. Carroll <am...@network-geographics.com>
Committed: Tue Jul 30 15:15:58 2013 -0500
----------------------------------------------------------------------
.../blacklist-plugin.en.rst | 89 +++++++++---------
...ssing-the-transaction-being-processed.en.rst | 65 +++++++-------
.../setting-a-global-hook.en.rst | 31 ++++---
.../setting-up-a-transaction-hook.en.rst | 65 +++++++-------
.../working-with-http-header-functions.en.rst | 94 ++++++++++----------
5 files changed, 169 insertions(+), 175 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/7c1c7fdb/doc/sdk/header-based-plugin-examples/blacklist-plugin.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/header-based-plugin-examples/blacklist-plugin.en.rst b/doc/sdk/header-based-plugin-examples/blacklist-plugin.en.rst
index 5122308..91c782d 100644
--- a/doc/sdk/header-based-plugin-examples/blacklist-plugin.en.rst
+++ b/doc/sdk/header-based-plugin-examples/blacklist-plugin.en.rst
@@ -3,20 +3,20 @@ The Blacklist Plugin
.. Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
The sample blacklisting plugin included in the Traffic Server SDK is
``blacklist-1.c``. This plugin checks every incoming HTTP client request
@@ -49,19 +49,19 @@ Traffic Server has a multi-threaded design, race conditions can occur if
several threads try to access the same continuation's data.
Here is how the static parent continuation is created in
-``blacklist-1.c``:
+:file:blacklist-1.c`:
-::
+.. code-block:: c
- :::c
- void
- TSPluginInit (int argc, const char *argv[])
- { ...
- TSCont contp;
-
- contp = TSContCreate (blacklist_plugin, NULL);
- ...
- }
+ void
+ TSPluginInit (int argc, const char *argv[])
+ {
+ // ...
+ TSCont contp;
+
+ contp = TSContCreate (blacklist_plugin, NULL);
+ // ...
+ }
The handler function for the plugin is ``blacklist_plugin``, and the
mutex is null. The continuation handler function's job is to handle the
@@ -69,26 +69,25 @@ events that are sent to it; accordingly, the ``blacklist_plugin``
routine consists of a switch statement that covers each of the events
that might be sent to it:
-::
-
- :::c
- static int
- blacklist_plugin (TSCont contp, TSEvent event, void *edata)
- {
- TSHttpTxn txnp = (TSHttpTxn) edata;
- switch (event) {
- case TS_EVENT_HTTP_OS_DNS:
- handle_dns (txnp, contp);
- return 0;
- case TS_EVENT_HTTP_SEND_RESPONSE_HDR:
- handle_response (txnp);
- return 0;
- default:
- TSDebug ("blacklist_plugin", "This event was unexpected: %d\n", );
- break;
- }
- return 0;
- }
+.. code-block:: c
+
+ static int
+ blacklist_plugin (TSCont contp, TSEvent event, void *edata)
+ {
+ TSHttpTxn txnp = (TSHttpTxn) edata;
+ switch (event) {
+ case TS_EVENT_HTTP_OS_DNS:
+ handle_dns (txnp, contp);
+ return 0;
+ case TS_EVENT_HTTP_SEND_RESPONSE_HDR:
+ handle_response (txnp);
+ return 0;
+ default:
+ TSDebug ("blacklist_plugin", "This event was unexpected: %d\n", );
+ break;
+ }
+ return 0;
+ }
When you write handler functions, you have to anticipate any events that
might be sent to the handler by hooks or by other functions. In the
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/7c1c7fdb/doc/sdk/header-based-plugin-examples/blacklist-plugin/accessing-the-transaction-being-processed.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/header-based-plugin-examples/blacklist-plugin/accessing-the-transaction-being-processed.en.rst b/doc/sdk/header-based-plugin-examples/blacklist-plugin/accessing-the-transaction-being-processed.en.rst
index 084c091..75feed1 100644
--- a/doc/sdk/header-based-plugin-examples/blacklist-plugin/accessing-the-transaction-being-processed.en.rst
+++ b/doc/sdk/header-based-plugin-examples/blacklist-plugin/accessing-the-transaction-being-processed.en.rst
@@ -3,20 +3,20 @@ Accessing the Transaction Being Processed
.. Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
A continuation's handler function is of type ``TSEventFunc``; the
prototype is as follows:
@@ -36,25 +36,24 @@ data type that represents HTTP transactions). Your plugin can then do
things with the transaction. Here's how it looks in the code for the
Blacklist plugin's handler:
-::
-
- :::c
- static int
- blacklist_plugin (TSCont contp, TSEvent event, void *edata)
- {
- TSHttpTxn txnp = (TSHttpTxn) edata;
- switch (event) {
- case TS_EVENT_HTTP_OS_DNS:
- handle_dns (txnp, contp);
- return 0;
- case TS_EVENT_HTTP_SEND_RESPONSE_HDR:
- handle_response (txnp);
- return 0;
- default:
- break;
- }
- return 0;
- }
+.. code-block:: c
+
+ static int
+ blacklist_plugin (TSCont contp, TSEvent event, void *edata)
+ {
+ TSHttpTxn txnp = (TSHttpTxn) edata;
+ switch (event) {
+ case TS_EVENT_HTTP_OS_DNS:
+ handle_dns (txnp, contp);
+ return 0;
+ case TS_EVENT_HTTP_SEND_RESPONSE_HDR:
+ handle_response (txnp);
+ return 0;
+ default:
+ break;
+ }
+ return 0;
+ }
For example: when the origin server DNS lookup event is sent,
``blacklist_plugin`` can call ``handle_dns``\ and pass ``txnp`` as an
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/7c1c7fdb/doc/sdk/header-based-plugin-examples/blacklist-plugin/setting-a-global-hook.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/header-based-plugin-examples/blacklist-plugin/setting-a-global-hook.en.rst b/doc/sdk/header-based-plugin-examples/blacklist-plugin/setting-a-global-hook.en.rst
index df86efd..749ada2 100644
--- a/doc/sdk/header-based-plugin-examples/blacklist-plugin/setting-a-global-hook.en.rst
+++ b/doc/sdk/header-based-plugin-examples/blacklist-plugin/setting-a-global-hook.en.rst
@@ -3,30 +3,29 @@ Setting a Global Hook
.. Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
Global hooks are always added in ``TSPluginInit`` using
``TSHttpHookAdd``. The two arguments of ``TSHttpHookAdd`` are the hook
ID and the continuation to call when processing the event corresponding
to the hook. In ``blacklist-1.c``, the global hook is added as follows:
-::
+.. code-block:: c
- :::c
- TSHttpHookAdd (TS_HTTP_OS_DNS_HOOK, contp);
+ TSHttpHookAdd (TS_HTTP_OS_DNS_HOOK, contp);
Above, ``TS_HTTP_OS_DNS_HOOK`` is the ID for the origin server DNS
lookup hook and ``contp`` is the parent continuation created earlier.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/7c1c7fdb/doc/sdk/header-based-plugin-examples/blacklist-plugin/setting-up-a-transaction-hook.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/header-based-plugin-examples/blacklist-plugin/setting-up-a-transaction-hook.en.rst b/doc/sdk/header-based-plugin-examples/blacklist-plugin/setting-up-a-transaction-hook.en.rst
index 0590e09..ed2070e 100644
--- a/doc/sdk/header-based-plugin-examples/blacklist-plugin/setting-up-a-transaction-hook.en.rst
+++ b/doc/sdk/header-based-plugin-examples/blacklist-plugin/setting-up-a-transaction-hook.en.rst
@@ -3,20 +3,20 @@ Setting Up a Transaction Hook
.. Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
The Blacklist plugin sends "access forbidden" messages to clients if
their requests are directed to blacklisted hosts. Therefore, the plugin
@@ -25,26 +25,25 @@ HTTP state machine reaches the "send response header" event. In the
Blacklist plugin's ``handle_dns`` routine, the transaction hook is added
as follows:
-::
+.. code-block:: c
- :::c
- TSMutexLock (sites_mutex);
- for (i = 0; i < nsites; i++) {
- if (strncmp (host, sites[i], host_length) == 0) {
- printf ("blacklisting site: %s\n", sites[i]);
- TSHttpTxnHookAdd (txnp,
- TS_HTTP_SEND_RESPONSE_HDR_HOOK,
- contp);
- TSHandleMLocRelease (bufp, hdr_loc, url_loc);
- TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
- TSHttpTxnReenable (txnp, TS_EVENT_HTTP_ERROR);
- TSMutexUnlock (sites_mutex);
- return;
- }
- }
- TSMutexUnlock (sites_mutex);
- done:
- TSHttpTxnReenable (txnp, TS_EVENT_HTTP_CONTINUE);
+ TSMutexLock (sites_mutex);
+ for (i = 0; i < nsites; i++) {
+ if (strncmp (host, sites[i], host_length) == 0) {
+ printf ("blacklisting site: %s\n", sites[i]);
+ TSHttpTxnHookAdd (txnp,
+ TS_HTTP_SEND_RESPONSE_HDR_HOOK,
+ contp);
+ TSHandleMLocRelease (bufp, hdr_loc, url_loc);
+ TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
+ TSHttpTxnReenable (txnp, TS_EVENT_HTTP_ERROR);
+ TSMutexUnlock (sites_mutex);
+ return;
+ }
+ }
+ TSMutexUnlock (sites_mutex);
+ done:
+ TSHttpTxnReenable (txnp, TS_EVENT_HTTP_CONTINUE);
This code fragment shows some interesting features. The plugin is
comparing the requested site to the list of blacklisted sites. While the
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/7c1c7fdb/doc/sdk/header-based-plugin-examples/blacklist-plugin/working-with-http-header-functions.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/header-based-plugin-examples/blacklist-plugin/working-with-http-header-functions.en.rst b/doc/sdk/header-based-plugin-examples/blacklist-plugin/working-with-http-header-functions.en.rst
index bb510e3..9f0fb4f 100644
--- a/doc/sdk/header-based-plugin-examples/blacklist-plugin/working-with-http-header-functions.en.rst
+++ b/doc/sdk/header-based-plugin-examples/blacklist-plugin/working-with-http-header-functions.en.rst
@@ -3,57 +3,55 @@ Working with HTTP Header Functions
.. Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
The Blacklist plugin examines the host header in every client
transaction. This is done in the ``handle_dns`` routine, using
-``TSHttpTxnClientIPGet``, ``TSHttpHdrUrlGet``, and ``TSUrlHostGet``.
-
-::
-
- :::c
- static void
- handle_dns (TSHttpTxn txnp, TSCont contp)
- {
- TSMBuffer bufp;
- TSMLoc hdr_loc;
- TSMLoc url_loc;
- const char *host;
- int i;
-
- if (!TSHttpTxnClientIPGet (txnp, &bufp, &hdr_loc)) {
- TSError ("couldn't retrieve client request header\n");
- goto done;
- }
-
- url_loc = TSHttpHdrUrlGet (bufp, hdr_loc);
-
- if (!url_loc) {
- TSError ("couldn't retrieve request url\n");
- TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
- goto done;
- }
-
- host = TSUrlHostGet (bufp, url_loc, NULL);
- if (!host) {
- TSError ("couldn't retrieve request hostname\n");
- TSHandleMLocRelease (bufp, hdr_loc, url_loc);
- TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
- goto done;
- }
+``TSHttpTxnClientReqGet``, ``TSHttpHdrUrlGet``, and ``TSUrlHostGet``.
+
+.. code-block:: c
+
+ static void
+ handle_dns (TSHttpTxn txnp, TSCont contp)
+ {
+ TSMBuffer bufp;
+ TSMLoc hdr_loc;
+ TSMLoc url_loc;
+ const char *host;
+ int i;
+ int host_length;
+
+ if (TSHttpTxnClientReqGet(txnp, &bufp, &hdr_loc) != TS_SUCCESS) {
+ TSError("couldn't retrieve client request header\n");
+ goto done;
+ }
+
+ if (TSHttpHdrUrlGet(bufp, hdr_loc, &url_loc) != TS_SUCCESS) {
+ TSError("couldn't retrieve request url\n");
+ TSHandleMLocRelease(bufp, TS_NULL_MLOC, hdr_loc);
+ goto done;
+ }
+
+ host = TSUrlHostGet(bufp, url_loc, &host_length);
+ if (!host) {
+ TSError("couldn't retrieve request hostname\n");
+ TSHandleMLocRelease(bufp, hdr_loc, url_loc);
+ TSHandleMLocRelease(bufp, TS_NULL_MLOC, hdr_loc);
+ goto done;
+ }
To access the host header, the plugin must first get the client request,
retrieve the URL portion, and then obtain the host header. See `HTTP