NAME

       TSRemapInit - traffic Server remap plugin entry points

SYNOPSIS

          #include <ts/ts.h>
          #include <ts/remap.h>

       TSReturnCode TSRemapInit(TSRemapInterface *api_info, char *errbuff, int errbuff_size)

       void TSRemapPreConfigReload(void)

       void TSRemapPostConfigReload(TSReturnCode reloadStatus)

       void TSRemapDone(void)

       TSRemapStatus TSRemapDoRemap(void *ih, TSHttpTxn rh, TSRemapRequestInfo *rri)

       TSReturnCode  TSRemapNewInstance(int  argc,  char  *argv[],  void **ih, char *errbuff, int
       errbuff_size)

       void TSRemapDeleteInstance(void*)

       void TSRemapOSResponse(void *ih, TSHttpTxn rh, int os_response_type)

DESCRIPTION

       The Traffic Server  remap  interface  provides  a  simplified  mechanism  for  plugins  to
       manipulate  HTTP  transactions.  A  remap  plugin  is  not  global;  it is configured on a
       per-remap rule basis, which enables you to customize how  URLs  are  redirected  based  on
       individual  rules in remap.config.  Writing a remap plugin consists of implementing one or
       more of the remap entry points and  configuring  remap.config  to  route  the  transaction
       through  your  plugin.  Multiple  remap  plugins can be specified for a single remap rule,
       resulting in a remap plugin chain where each plugin is given an opportunity to examine the
       HTTP transaction.

       TSRemapInit()  is  a  required entry point. This function will be called once when Traffic
       Server loads the plugin. If the optional TSRemapDone() entry point is  available,  Traffic
       Server will call then when unloading the remap plugin.

       A  remap  plugin  may  be  invoked for different remap rules. Traffic Server will call the
       entry point each time a plugin is specified in a remap rule. When a remap plugin  instance
       is  no  longer  required, Traffic Server will call TSRemapDeleteInstance(). At that point,
       it's safe to remove any data or continuations associated with that instance.

       TSRemapDoRemap() is called for each HTTP transaction. This is a mandatory entry point.  In
       this function, the remap plugin may examine and modify the HTTP transaction.

       TSRemapPreConfigReload()  is called before the parsing of a new remap configuration starts
       to notify plugins of the coming configuration reload. It is called on all  already  loaded
       plugins,  invoked  by  current  and  all  previous  still  used configurations. This is an
       optional entry point.

       TSRemapPostConfigReload() is called to indicate the end of  the  new  remap  configuration
       load. It is called on the newly and previously loaded plugins, invoked by the new, current
       and previous still used configurations. It also indicates whether the configuration reload
       was  successful  by passing TSREMAP_CONFIG_RELOAD_FAILURE in case of failure and to notify
       the  plugins  if  they  are  going  to  be  part  of  the  new  configuration  by  passing
       TSREMAP_CONFIG_RELOAD_SUCCESS_PLUGIN_USED  or TSREMAP_CONFIG_RELOAD_SUCCESS_PLUGIN_UNUSED.
       This is an optional entry point.

       Generally speaking, calls to these functions are mutually exclusive. The exception is  for
       functions   which   take   an   HTTP   transaction   as   a   parameter.  Calls  to  these
       transaction-specific functions for different transactions  are  not  necessarily  mutually
       exclusive of each other.

       For further information, see Remap Plugins.

TYPES

       type TSRemapStatus
              Status return value for remap callback.

              TSREMAP_DID_REMAP
                     The remap callback modified the request.

              TSREMAP_DID_REMAP_STOP
                     The remap callback modified the request and that no more remapping callbacks
                     should be invoked.

              TSREMAP_NO_REMAP
                     The remap callback did not modify the request.

              TSREMAP_NO_REMAP_STOP
                     The remap callback did not modify the request and that no further  remapping
                     callbacks should be invoked.

              TSREMAP_ERROR
                     The remapping attempt in general failed and the transaction should fail with
                     an error return to the user agent.

       type TSRemapReloadStatus

              TSREMAP_CONFIG_RELOAD_FAILURE
                     Notify the plugin that configuration parsing failed.

              TSREMAP_CONFIG_RELOAD_SUCCESS_PLUGIN_USED
                     Configuration  parsing  succeeded  and  plugin   was   used   by   the   new
                     configuration.

              TSREMAP_CONFIG_RELOAD_SUCCESS_PLUGIN_UNUSED
                     Configuration  parsing  succeeded  but  plugin  was  NOT  used  by  the  new
                     configuration.

RETURN VALUES

       TSRemapInit() and TSRemapNewInstance() should return TS_SUCCESS on success,  and  TS_ERROR
       otherwise. A return value of TS_ERROR is unrecoverable.

       TSRemapDoRemap()  returns  a  status  code that indicates whether the HTTP transaction has
       been modified and whether Traffic Server should continue to evaluate the  chain  of  remap
       plugins.  If  the  transaction was modified, the plugin should return TSREMAP_DID_REMAP or
       TSREMAP_DID_REMAP_STOP;    otherwise    it    should    return     TSREMAP_NO_REMAP     or
       TSREMAP_NO_REMAP_STOP.  If  Traffic  Server  should not send the transaction to subsequent
       plugins in  the  remap  chain,  return  TSREMAP_NO_REMAP_STOP  or  TSREMAP_DID_REMAP_STOP.
       Returning  TSREMAP_ERROR  causes  Traffic  Server  to  stop evaluating the remap chain and
       respond with an error.

SEE ALSO

       TSAPI(3ts)

COPYRIGHT

       2022, dev@trafficserver.apache.org