Plugin API

By means of the plugin apiopen in new window it is possible to register hooks at important program points of httpYac.

export interface HttpyacHooksApi{
  readonly version: string;
  readonly rootDir?: PathLike;
  readonly httpFile: Readonly<HttpFile>;
  readonly config: EnvironmentConfig;
  readonly hooks: HttpFileHooks;
  readonly log: LogHandler;
  readonly fileProvider: FileProvider,
  readonly sessionStore: SessionStore,
  readonly userInteractionProvider: UserInteractionProvider;
  getHookCancel(): symbol;
}

version

  • Type: string

The version string for the httpYac api version that is loading the plugin.

rootDir

  • Type: string

The project root directory of current http File.

httpFile

http file prepared for parsing, which has no regions yet.

config

Environment configuration determined for the current execution

log

The log module provides a simple debugging console. The output channel is redirected per use case

fileProvider

Data access layer for file access

WARNING

The VS Code extension also supports loading virtual documentsopen in new window. Direct access via fs is not always possible.

sessionStore

Service to store user sessions. The user has the possibility to delete them manually

userInteractionProvider

enables interaction with the user

getHookCancel

function to retrieve javascript symbol, which is used to cancel execution of hooks

hooks

List of hooks for which own program logic can be registered

export interface HttpFileHooks{
  readonly parse: ParseHook,
  readonly parseEndRegion: ParseEndRegionHook,
  readonly replaceVariable: ReplaceVariableHook;
  readonly provideEnvironments: ProvideEnvironmentsHook;
  readonly provideVariables: ProvideVariablesHook;


  readonly onRequest: OnRequestHook;
  readonly onResponse: OnResponseHook,
  readonly responseLogging: ResponseLoggingHook,
}

TIP

httpYac uses most of the hooks itself for its own application logic. Just look in the source code

ParseHook

hook for parsing http file. The goal is to determine and register the necessary actions for this line.

TIP

As soon as a hook determines a result, the processing for this row is aborted and the subsequent hooks are not processed (BailHook).

WARNING

Hook request and requestBody always returns a result. It is necessary to register your own parser before this one

module.exports = (api) => {
  api.hooks.parse.addHook('getCoffee', function (getLineReader, context) {
    const lineReader = getLineReader();
    let next = lineReader.next();
    if (!next.done) {
      // regex match if line is javascript start line
      const match = /^\s*GET\s+coffee?$/ui.test(next.value.textLine);
      if (!match) {
        return false;
      }

      context.httpRegion.hooks.execute.addHook('get_coffee', async context => {
        context.scriptConsole?.info?.(`get coffee`);
      });
      return { // return nextParserLine and symbol for lines
        nextParserLine: next.value.line,
        symbols: [{
          name: 'coffee',
          description: 'coffee with some milk, no sugar',
          kind: 'comment',
          startLine: next.value.line,
          startOffset: 0,
          endLine: next.value.line,
          endOffset: next.value.textLine.length,
        }]
      };
    }
    return false;
  }, {
    before: ['request']
  });
}

full exampleopen in new window

ParseEndRegionHook

hook after identifying new http region

ReplaceVariableHook

hook to replace variable in request line, header or request body

module.exports = (api) => {
  api.hooks.replaceVariable.addHook('changeXCoffeeHeader', async function (text, type) {
    if (type === 'X-Coffee') {
      return 'Black';
    }
    return text;
  });
}

full exampleopen in new window

ProvideVariablesHook

hook to provide custom variables

module.exports = (api) => {
  api.hooks.provideVariables.addHook('getCoffee', async function (envs) {
    if (envs && envs.length > 0) {
      return {
        system: envs[0],
        coffee: 'coffee with milk, no sugar',
      }
    }
    return {
      system: 'none',
      coffee: 'black',
    };
  });
  api.hooks.provideEnvironments.addHook('getCoffeeEnvironments', async function () {
    return ['kitchen', 'Riedbachstüberl'];
  });
}

 
 
 
 
 
 
 
 
 
 
 
 




full exampleopen in new window

ProvideEnvironmentsHook

hook to provide environments

module.exports = (api) => {
  api.hooks.provideVariables.addHook('getCoffee', async function (envs) {
    if (envs && envs.length > 0) {
      return {
        system: envs[0],
        coffee: 'coffee with milk, no sugar',
      }
    }
    return {
      system: 'none',
      coffee: 'black',
    };
  });
  api.hooks.provideEnvironments.addHook('getCoffeeEnvironments', async function () {
    return ['kitchen', 'Riedbachstüberl'];
  });
}













 
 
 

full exampleopen in new window

OnRequest Hook

hook called before every request call

module.exports = (api) => {
  api.hooks.onRequest.addHook('getCoffee', function (request) {
    request.headers = Object.assign({
      'X-Coffee':  'coffee with milk, no sugar',
     }, request.headers);
  });
}

full exampleopen in new window

OnResponse Hook

hook called after every response

module.exports = (api) => {
  api.hooks.onResponse.addHook('getCoffee', function (response) {
    response.body = 'coffee with milk, no sugar';
    delete response.parsedBody;
    delete response.prettyPrintBody;
  });
}

full exampleopen in new window

ResponseLoggingHook

hook called for every logging of a response.

module.exports = (api) => {
  api.hooks.responseLogging.addHook('removeHeadersAndRequest', async function (response) {
    delete response.headers;
    delete response.request;
    return response;
  });
}

full exampleopen in new window

Last Updated: