Installing the Enforcer

Communicate with the HUMAN Backend

For the enforcer to communicate with HUMAN Collector server, a specific "backend" server must be added and configured in the Fastly UI (or using the contrib/pxbackend.sh script).
Backend parameters (replace ${APP_ID} with your HUMAN Application ID):

Name: PX_BACKEND_${APP_ID}
Hostname: sapi-${APP_ID}.perimeterx.net
Override host: sapi-${APP_ID}.perimeterx.net
Use SSL/TLS: Yes

Module installation

Include perimeterx-fastly-enforcer dependency to Cargo.toml:

cargo add perimeterx-fastly-enforcer

Module integration

To integrate HUMAN Rust module into an existing Rust code, the following base snippet could be used:

let mut px: PXEnforcer = PXEnforcer::new(perimeterx_fastly_enforcer::DEFAULT_CONFIGSTORE_NAME);
let px_result = px.enforce(&mut req)?;
if let Some(r) = px_result {
    return Ok(r);
};

//... communicate with Origin server / process request and response

px.post_enforce(&response);

Enforcer API

Initialize PXEnforcer structure, it takes a name of Fastly "ConfigStore" (it's possible to use the default name: perimeterx_fastly_enforcer::DEFAULT_CONFIGSTORE_NAME)

pub fn new(config_store_name: &str) -> Self

This function takes a request and returns a result which basically contains a response (for "blocked" or "first party" requests):

pub fn enforce(&mut self, req: &mut Request) -> Result<Option<Response>, Error>

At the end of request processing, the following function must be called to finalize HUMAN enforcer code:

pub fn post_enforce(&self, res: &Response)

It is possible to access HUMANContext structure with various Enforcer variables via px.ctx member:

// send "score" value to the Origin
req.set_header("x-px-score", px.ctx.score.to_string());

To set "custom_parameters" variables, the following callback function could be used:

pub type PXEnrichCustomParamsFn = fn (req: &Request, conf: &PXConfig, params: &mut PXCustomParams);

where:
req: fastly::Request
conf: HUMANConfig
params: modifiable structure with custom_param1 .. custom_param10 fields

To set custom parameters callback function, use the following setter:

pub fn set_enrich_custom_params_fn(&mut self, f: PXEnrichCustomParamsFn)

Sample code

This is the simplest example on how to use HUMAN Rust module:

use fastly::{Error, Request, Response};
use perimeterx_fastly_enforcer::pxenforce::PXEnforcer;

const ORIGIN_BACKEND: &str = "origin_backend";

fn send_to_origin(req: Request) -> Result<Response, Error> {
    println!("sending to Origin...");
    match req.send(ORIGIN_BACKEND) {
        Ok(r) => return Ok(r),
        Err(e) => return Err(e.into()),
    }
}

#[fastly::main]
fn main(mut req: Request) -> Result<Response, Error> {

    let mut px: PXEnforcer = PXEnforcer::new(perimeterx_fastly_enforcer::DEFAULT_CONFIGSTORE_NAME);

    // execute PX Enforcer for Request
    let px_result = px.enforce(&mut req)?;

    // return, if it's a "blocked" or "first party" response
    if let Some(r) = px_result {
        return Ok(r);
    };

    // ... process Client request ...

    // we can access "PXContext" structure.
    // as an example: send "score" value to the Origin
    req.set_header("x-px-score", px.ctx.score.to_string());

    // a client function to communicate with the Origin
    let response = send_to_origin(req)?;

    // ... process Origin response ...

    // must be called at the end
    px.post_enforce(&response);

    // we are ok to send response back to client
    return Ok(response);
}

Updated 12 days ago