XrdXrootdRedirHelper Class Reference

#include <XrdXrootdRedirHelper.hh>

Collaboration diagram for XrdXrootdRedirHelper:

Public Types
enum class	Outcome {   Unchanged ,   Replaced ,   Error }

Static Public Member Functions
static void	Init (XrdXrootdRedirPI *pi, XrdSysError *eDest, int ipHold)
static bool	IsActive ()
static bool	ParseURL (const char *url, std::string &urlHead, std::string &host, std::string &port, std::string &urlTail)
static Outcome	Redirect (const char *trg, int &port, XrdNetAddrInfo &clientAddr, std::string &outTarget, std::string &errMsg)
static void	SetClockForTesting (std::function< time_t()> nowFn)

Detailed Description

Process-wide adapter around the redirect plugin (XrdXrootdRedirPI) so the plugin can be invoked uniformly from the XRootD protocol and from any other subsystem that produces redirect targets (e.g. the HTTP TPC handler addressed by issue #2767).

Responsibilities centralised here so they do not need to be reproduced at every call site:

• the static plugin pointer plus the logger used for diagnostics;
• a cache of XrdNetAddrInfo objects for previously-resolved redirect targets (each plugin call needs the target's resolved netaddr, which is comparatively expensive to obtain);
• the empty / "<new target>" / "!<error>" return-string contract of the plugin, normalised into a tri-state Outcome.

The class is non-instantiable; it is initialised once by Init() (called from XrdXrootdConfig.cc after the redirect plugin has been loaded) and its Redirect() static method is then invoked concurrently from any number of worker threads. When no plugin is configured IsActive() returns false and Redirect() is an inexpensive no-op.

Definition at line 59 of file XrdXrootdRedirHelper.hh.

Member Enumeration Documentation

Outcome

enum XrdXrootdRedirHelper::Outcome

strong

Tri-state outcome returned by Redirect().

Mirrors the three cases of the plugin's return-string contract:

• empty string -> Unchanged: caller keeps the original target
• "<new target>" -> Replaced: caller emits the new target
• "!<message>" -> Error: caller fails the request, surfaces the message

Enumerator
Unchanged
Replaced
Error

Definition at line 73 of file XrdXrootdRedirHelper.hh.

{ Unchanged, Replaced, Error };

Member Function Documentation

Init()

void XrdXrootdRedirHelper::Init ( XrdXrootdRedirPI *  pi, XrdSysError *  eDest, int  ipHold  )

static

Initialise the helper. Must be called exactly once, after the redirect plugin has been loaded and before any worker thread invokes Redirect(). Calling Init(nullptr, ...) is a valid no-op that simply disarms the helper.

Parameters

pi	pointer to the loaded redirect plugin, or nullptr if no plugin was loaded. When nullptr, IsActive() returns false and Redirect() always returns Unchanged.
eDest	logger used to report cache-population failures. Must not be nullptr when pi is non-null.
ipHold	number of seconds for which a successfully-resolved target XrdNetAddrInfo is reused before being refreshed. Mirrors XrdXrootdProtocol::redirIPHold.

Definition at line 164 of file XrdXrootdRedirHelper.cc.

{
   gPlugin = pi;
   gLog    = eDest;
   gIPHold = ipHold;
}

References eDest.

Referenced by XrdXrootdProtocol::Configure().

Here is the caller graph for this function:

IsActive()

bool XrdXrootdRedirHelper::IsActive ( )

static

Returns

true iff a redirect plugin has been registered via Init().

Definition at line 176 of file XrdXrootdRedirHelper.cc.

{ return gPlugin != nullptr; }

ParseURL()

bool XrdXrootdRedirHelper::ParseURL ( const char *  url, std::string &  urlHead, std::string &  host, std::string &  port, std::string &  urlTail  )

static

Parse a scheme://host[:port][/tail] redirect URL into its components.

Exposed as a static method, rather than kept private to the .cc, so the URL grammar Redirect() relies on for URL-form targets can be unit-tested directly without a plugin, the netaddr cache or DNS. Redirect() is its only production caller.

Parameters

url	URL to parse. Must not be nullptr.
urlHead	output: scheme prefix up to and including "://".
host	output: host name, with any ":port" suffix removed.
port	output: port string, or "" when no port is present.
urlTail	output: path/query tail including the leading '/', or "" when the URL has no path.

Returns

true on success. false when url is not a parseable scheme://host[:port][/tail] URL; the output parameters are then left in an unspecified state.

Definition at line 275 of file XrdXrootdRedirHelper.cc.

{
   const char *hBeg = strstr(url, "://");
   if (!hBeg) return false;
   hBeg += 3;
   urlHead.assign(url, hBeg - url);
 
   // Split off the path/query tail; require the host[:port] authority that
   // precedes it to be at least two characters long.
   if (const char *tail = strstr(hBeg, "/"); !tail)
      {urlTail.clear(); host = hBeg;}
      else {if (tail - hBeg < 3) return false;
            host.assign(hBeg, tail - hBeg);
            urlTail = tail;
           }
 
   // Separate an optional ":port" suffix from the host.
   port.clear();
   if (size_t colon = host.find(':'); colon != std::string::npos)
      {port.assign(host, colon + 1, std::string::npos);
       host.erase(colon);
      }
   return true;
}

Referenced by Redirect().

Here is the caller graph for this function:

Redirect()

XrdXrootdRedirHelper::Outcome XrdXrootdRedirHelper::Redirect ( const char *  trg, int &  port, XrdNetAddrInfo &  clientAddr, std::string &  outTarget, std::string &  errMsg  )

static

Run a redirect target through the redirect plugin.

Single entry point for both redirect forms; port selects which one, mirroring the calling convention of XrdXrootdProtocol::fsRedirPI():

• port >= 0 : trg is a host[?cgi] target and port is its numeric port. The target is split internally (via splitHostCgi) and the plugin's Redirect() entry point is invoked; port is rewritten in place when the plugin asks for a different port.
• port < 0 : trg is a full scheme://host[:port][/tail] URL. It is parsed internally (via ParseURL) and the plugin's RedirectURL() entry point is invoked. Here port doubles as the plugin's rdrOpts argument; because it is also the protocol's URL marker it is passed to the plugin but left unmodified on return. A URL that cannot be parsed is logged and yields Outcome::Unchanged without invoking the plugin.

Used by the XRootD protocol (fsRedirPI) for both forms and by the HTTP TPC handler (issue #2767), which only ever passes the host[?cgi] form.

Parameters

trg	redirect target: host[?cgi] when port >= 0, or a scheme://host[:port][/tail] URL when port < 0. A nullptr is tolerated defensively and yields Outcome::Unchanged without invoking the plugin.
port	in/out, doubling as the host-vs-URL selector; see the per-form description above.
clientAddr	network info of the client being redirected.
outTarget	output: when Replaced, holds the new redirect target. Untouched otherwise.
errMsg	output: when Error, holds the plugin's error message with the contract's leading '!' already stripped. Untouched otherwise.

Returns

Unchanged if no plugin is configured, the target's network address could not be resolved, a URL target could not be parsed, or the plugin returned an empty string. Replaced if the plugin returned a new target. Error if the plugin returned a fatal error.

Note

Thread-safe. Internal state is protected by a mutex; the caller may invoke this from any thread once Init() has returned.

Definition at line 199 of file XrdXrootdRedirHelper.cc.

{
   if (!gPlugin || !trg) return Outcome::Unchanged;
 
   std::string pluginReply;   // raw plugin reply, filled by the branch below
   uint16_t    hostPort = 0;  // host form: the plugin's port (in/out)
 
   if (port >= 0)
      {// Host[?cgi] form: split the target and invoke the plugin's host+port
       // Redirect() entry point, which may rewrite the port in place.
       if (port > UINT16_MAX)
          {if (gLog) gLog->Emsg("RedirPI", "Redirect port out of range -",
                                std::to_string(port).c_str());
           return Outcome::Unchanged;
          }
       std::string host;
       std::string cgi;
       splitHostCgi(trg, host, cgi);
 
       // The plugin call needs the target's resolved netaddr.  If we cannot
       // produce one the safest fallback is to leave the redirect alone
       // (Unchanged) so the caller emits the original target unmodified.
       THandle T;
       T.Info = LookupTarget(host.c_str(), port);
       if (!T.Info) return Outcome::Unchanged;
 
       hostPort    = static_cast<uint16_t>(port);
       pluginReply = gPlugin->Redirect(host.c_str(), hostPort, cgi.c_str(),
                                       T.Info->netAddr, clientAddr);
      } else {
       // URL form: parse scheme://host[:port][/tail] and invoke the plugin's
       // RedirectURL() entry point.  port doubles as the rdrOpts argument and
       // is the protocol's URL marker, so it is passed in but left unmodified.
       // A URL we cannot parse is not salvageable: skip the plugin and report
       // Unchanged so the caller emits the original target unmodified.
       std::string urlHead;
       std::string host;
       std::string urlPort;
       std::string urlTail;
       if (!ParseURL(trg, urlHead, host, urlPort, urlTail))
          {if (gLog) gLog->Emsg("RedirPI", "Invalid redirect URL -", trg);
           return Outcome::Unchanged;
          }
 
       // The cache is keyed by host alone (no scheme, no port suffix); pass
       // -1 so the netaddr resolution does not bind to any specific port.  A
       // resolution failure falls back to Unchanged, as in the host form.
       THandle T;
       T.Info = LookupTarget(host.c_str(), -1);
       if (!T.Info) return Outcome::Unchanged;
 
       int rdrOpts = port;
       pluginReply = gPlugin->RedirectURL(urlHead.c_str(), host.c_str(),
                                          urlPort.c_str(), urlTail.c_str(),
                                          rdrOpts, T.Info->netAddr,
                                          clientAddr);
      }
 
   // Translate the plugin's "" / "<target>" / "!<msg>" return-string contract.
   if (pluginReply.empty())        return Outcome::Unchanged;
   if (pluginReply.front() == '!') { errMsg.assign(pluginReply, 1);
                                     return Outcome::Error; }
 
   // Replaced: commit the plugin's (possibly rewritten) port.  Host form only;
   // the URL form leaves port untouched as the protocol's URL marker.
   if (port >= 0) port = hostPort;
   outTarget = std::move(pluginReply);
   return Outcome::Replaced;
}

References XrdSysError::Emsg(), Error, ParseURL(), XrdXrootdRedirPI::Redirect(), XrdXrootdRedirPI::RedirectURL(), Replaced, splitHostCgi(), and Unchanged.

Here is the call graph for this function:

SetClockForTesting()

void XrdXrootdRedirHelper::SetClockForTesting ( std::function< time_t()>  nowFn )

static

====================== ONLY FOR TESTING, DO NOT USE ======================

Override the clock function used by the internal target-netaddr cache so unit tests can fast-forward past the ipHold expiry and exercise the refresh path of LookupTarget. Pass nullptr to restore the default clock (time(nullptr)).

Warning

This function exists solely to make XrdXrootdRedirHelper unit- testable. It must never be called from production code. Calling it from anywhere other than tests would replace the wall-clock with a fake clock for every redirect resolution in the whole process and silently break the cache TTL semantics.

Parameters

nowFn

function returning a time_t to be used in place of time(nullptr). Pass an empty function to restore the default.

Definition at line 189 of file XrdXrootdRedirHelper.cc.

{
   gNow = std::move(nowFn);
}

---

The documentation for this class was generated from the following files:

• XrdXrootdRedirHelper.hh
• XrdXrootdRedirHelper.cc