xref: /trafficserver/include/ts/remap.h (revision 78c7c0c0)
1 /** @file
2 
3   A brief file description
4 
5   @section license License
6 
7   Licensed to the Apache Software Foundation (ASF) under one
8   or more contributor license agreements.  See the NOTICE file
9   distributed with this work for additional information
10   regarding copyright ownership.  The ASF licenses this file
11   to you under the Apache License, Version 2.0 (the
12   "License"); you may not use this file except in compliance
13   with the License.  You may obtain a copy of the License at
14 
15       http://www.apache.org/licenses/LICENSE-2.0
16 
17   Unless required by applicable law or agreed to in writing, software
18   distributed under the License is distributed on an "AS IS" BASIS,
19   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20   See the License for the specific language governing permissions and
21   limitations under the License.
22  */
23 
24 #pragma once
25 
26 #ifndef tsapi
27 #define tsapi
28 #endif
29 
30 #ifdef __cplusplus
31 extern "C" {
32 #endif /* __cplusplus */
33 
34 #define TSREMAP_VMAJOR 3 /* major version number */
35 #define TSREMAP_VMINOR 0 /* minor version number */
36 #define TSREMAP_VERSION ((TSREMAP_VMAJOR << 16) | TSREMAP_VMINOR)
37 
38 typedef struct _tsremap_api_info {
39   unsigned long size;            /* in: sizeof(struct _tsremap_api_info) */
40   unsigned long tsremap_version; /* in: TS supported version ((major << 16) | minor) */
41 } TSRemapInterface;
42 
43 typedef struct _tm_remap_request_info {
44   /* Important: You should *not* release these buf pointers or TSMLocs from your plugin! */
45 
46   /* these URL mloc's are read only, use normal ts/ts.h APIs for accessing  */
47   TSMLoc mapFromUrl;
48   TSMLoc mapToUrl;
49 
50   /* the request URL mloc and buffer pointers are read-write. You can read and modify the
51    requestUrl using normal ts/ts.h APIs, which is how you change the destination URL. */
52   TSMLoc requestUrl;
53 
54   /* requestBufp and requestHdrp are the equivalent of calling TSHttpTxnClientReqGet(). */
55   TSMBuffer requestBufp;
56   TSMLoc requestHdrp;
57 
58   /* 0 - don't redirect, 1 - use the (new)request URL as a redirect */
59   int redirect;
60 } TSRemapRequestInfo;
61 
62 /* This is the type returned by the TSRemapDoRemap() callback */
63 typedef enum {
64   TSREMAP_NO_REMAP       = 0, /* No remapping was done, continue with next in chain */
65   TSREMAP_DID_REMAP      = 1, /* Remapping was done, continue with next in chain */
66   TSREMAP_NO_REMAP_STOP  = 2, /* No remapping was done, and stop plugin chain evaluation */
67   TSREMAP_DID_REMAP_STOP = 3, /* Remapping was done, but stop plugin chain evaluation */
68 
69   /* In the future, the following error codes can also be used:
70      -400 to -499
71      -500 to -599
72      ....
73      This would allow a plugin to generate an error page. Right now,
74      setting the return code to any negative number is equivalent to TSREMAP_NO_REMAP */
75   TSREMAP_ERROR = -1 /* Some error, that should generate an error page */
76 } TSRemapStatus;
77 
78 /* Status code passed to the plugin by TSRemapPostConfigReload() signaling
79  * (1) if the configuration reload was successful and
80  * (2) if (1) is successful show if the plugin was part of the new configuration */
81 typedef enum {
82   TSREMAP_CONFIG_RELOAD_FAILURE             = 0, /* notify the plugin that configuration parsing failed */
83   TSREMAP_CONFIG_RELOAD_SUCCESS_PLUGIN_USED = 1, /* configuration parsing succeeded and plugin was used by the new configuration */
84   TSREMAP_CONFIG_RELOAD_SUCCESS_PLUGIN_UNUSED =
85     2 /* configuration parsing succeeded but plugin was NOT used by the new configuration */
86 } TSRemapReloadStatus;
87 
88 /* ----------------------------------------------------------------------------------
89    These are the entry points a plugin can implement. Note that TSRemapInit() and
90    TSRemapDoRemap() are both required.
91    ----------------------------------------------------------------------------------
92 */
93 
94 /* Plugin initialization - called first.
95    Mandatory interface function.
96    Return: TS_SUCCESS
97            TS_ERROR - error, errbuf can include error message from plugin
98 */
99 tsapi TSReturnCode TSRemapInit(TSRemapInterface *api_info, char *errbuf, int errbuf_size);
100 
101 /* This gets called every time before remap.config is reloaded. This is complementary
102    to TSRemapInit() which gets called when the plugin is first loaded.
103    It is guaranteed to be called before TSRemapInit() and TSRemapNewInstance().
104    It cannot fail, or cause reload to stop here, it's merely a notification.
105    Optional function.
106    Params: none
107    Return: none
108 */
109 tsapi void TSRemapPreConfigReload(void);
110 
111 /* This gets called every time afterremap.config is reloaded. This is complementary
112    to TSRemapInit() which gets called when the plugin is first loaded.
113    It is guaranteed to be called after TSRemapInit() and TSRemapNewInstance().
114    It cannot fail, or cause reload to stop here, it's merely a notification that
115    the (re)load is done and provide a status of its success or failure..
116    Optional function.
117    Params: reloadStatus - TS_SUCCESS - (re)load was successful,
118                           TS_ERROR - (re)load failed.
119    Return: none
120 */
121 tsapi void TSRemapPostConfigReload(TSRemapReloadStatus reloadStatus);
122 
123 /* Remap new request
124    Mandatory interface function.
125    Remap API plugin can/should use SDK API function calls inside this function!
126    return: TSREMAP_NO_REMAP - No remapping was done, continue with next in chain
127            TSREMAP_DID_REMAP - Remapping was done, continue with next in chain
128            TSREMAP_NO_REMAP_STOP - No remapping was done, and stop plugin chain evaluation
129            TSREMAP_DID_REMAP_STOP -  Remapping was done, but stop plugin chain evaluation
130 */
131 tsapi TSRemapStatus TSRemapDoRemap(void *ih, TSHttpTxn rh, TSRemapRequestInfo *rri);
132 
133 /* Plugin shutdown, called when plugin is unloaded.
134    Optional function. */
135 tsapi void TSRemapDone(void);
136 
137 /* Plugin new instance. Create new plugin processing entry for unique remap record.
138    First two arguments in argv vector are - fromURL and toURL from remap record.
139    Please keep in mind that fromURL and toURL will be converted to canonical view.
140    Return: TS_SUCCESS
141            TS_ERROR - instance creation error
142 */
143 tsapi TSReturnCode TSRemapNewInstance(int argc, char *argv[], void **ih, char *errbuf, int errbuf_size);
144 tsapi void TSRemapDeleteInstance(void *);
145 
146 /* Check response code from Origin Server
147    os_response_type -> TSServerState
148    Remap API plugin can use InkAPI function calls inside TSRemapDoRemap()
149    Return: none
150 */
151 tsapi void TSRemapOSResponse(void *ih, TSHttpTxn rh, int os_response_type);
152 
153 #ifdef __cplusplus
154 }
155 #endif /* __cplusplus */
156