src/developer/shell/josh/lib/fidl.js - fuchsia - Git at Google

 // Copyright 2019 The Fuchsia Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.

 /**
  * @fileoverview Utilities for making FIDL calls to protocols.  Contains both
  * classes for interacting with FIDL definitions and for calling out to
  * services.
  */
 import * as fidl_internal from 'fidl_internal';

 (function(global) {

 // Classes and functions for managing FIDL IR and libraries

 // TODO(jeremymanson): We really only want to look in the /pkg/ directory.
 // This involves really turning the shell into a component, which we haven't
 // done yet.
 const IR_PATH = fidl_internal.irPath;

 /**
  * Programmatic representation of a library.  Contains fidling IR.
  */
 class Library {
   constructor(ir) {
     this.ir = ir;
     this.kinds = {
       bits: this.ir.bits_declarations,
       const : this.ir.const_declarations,
       enum: this.ir.enum_declarations,
       interface: this.ir.interface_declarations,
       service: this.ir.service_declarations,
       struct: this.ir.struct_declarations,
       table: this.ir.table_declarations,
       union: this.ir.union_declarations,
       xunion: this.ir.xunion_declarations,
       type_alias: this.ir.type_alias_declarations,
     }
   }

   /**
    * Given a particular protocol name (as in FIDL IR), return the IR in this
    * library that represents that protocol.
    */
   lookupProtocol(name) {
     const decl = this._findDeclaration(this.ir.interface_declarations, name);
     if (decl === null) {
       throw new Error(`No such protocol ${name}`);
     }
     return decl;
   }

   /**
    * Given a particular identifier name (as in FIDL IR), return the IR in this
    * library that represents that identifier.
    */
   lookupIdentifier(ident) {
     const kind = this.ir.declarations[ident];
     return [kind, this._findDeclaration(this.kinds[kind], ident)];
   }

   _findDeclaration(decls, name) {
     for (const decl of decls) {
       if (decl.name === name) {
         return decl;
       }
     }
     return null;
   }
 };

 const libraries = new Map();
 // If we ever reassign this, we need to call close() to delete it.
 var internalLibrary = null;

 /**
  * Converts the given string to JSON, converting 64-bit ordinals to
  * strings.
  *
  * @param {String} str the string containing the IR to convert.
  */
 function stringToJsonIr(str) {
   // Hack: replace 64-bit ordinals with strings.  Better support for BigInts would be better.
   let regex = /("ordinal"\s*:\s*)([0-9]+)\s*,/gi;
   str = str.replace(regex, '$1"$2",');
   regex = /("generated_ordinal"\s*:\s*)([0-9]+)\s*,/gi;
   str = str.replace(regex, '$1"$2",');
   return JSON.parse(str);
 }

 /**
  * Loads the IR for a given library.
  * libraryName should be of the form library.protocol
  *
  * Libraries are expected to be in a directory structure such that the filename
  * is the library name, with dots replaced by directory separators, ending with
  * .fidl.json.  This should be arranged by the build system.
  */
 function loadIR(libraryName) {
   if (internalLibrary == null) {
     internalLibrary = fidl_internal.newLibrary();
   }

   let maybeSeparator = '';
   if (IR_PATH[IR_PATH.length - 1] != '/') {
     maybeSeparator = '/';
   }
   const irPath = IR_PATH + maybeSeparator + libraryName.replace(/\./g, '/') + '.fidl.json';

   // Load for JavaScript-level operations, like tab-completion and exposing the fidling.
   // We should probably move more of this to native code over time, so that we don't have to
   // load libraries twice.
   try {
     const f = std.open(irPath, 'r');
     let str = f.readAsString();
     f.close();
     let ir = stringToJsonIr(str);
     libraries.set(ir.name, new Library(ir));
   } catch {
     throw 'FIDL definition for ' + libraryName + ' not found in ' + irPath;
   }

   // Load for C++ level operations, like encoding and decoding.
   if (!internalLibrary.loadLibrary(irPath)) {
     throw 'Internal error: Unable to load libraries for ' + libraryName;
   }
 }

 /**
  * Loads the IR for a given library.
  * libraryName should be of the form library.protocol
  *
  * Libraries are expected to be in a directory structure such that the filename
  * is the library name, with dots replaced by directory separators, ending with
  * .fidl.json.  This should be arranged by the build system.
  */
 function loadLibrary(libraryName) {
   if (!libraries.has(libraryName)) {
     loadIR(libraryName);
   }
   if (!libraries.has(libraryName)) {
     throw new Error(`Could not find IR for ${libraryName}`);
   } else {
     return libraries.get(libraryName);
   }
 }

 /**
  * Loads the given string containing FIDL JSON IR as a library.
  */
 function loadLibraryIr(irString) {
   let ir = stringToJsonIr(irString);
   if (!libraries.has(ir.name)) {
     libraries.set(ir.name, new Library(ir));
     // Load for C++ level operations, like encoding and decoding.
     if (internalLibrary == null) {
       internalLibrary = fidl_internal.newLibrary();
     }
     if (!internalLibrary.loadLibraryFromString(ir.name, JSON.stringify(ir))) {
       throw 'Internal error: Unable to load libraries for ' + ir.name;
     }
   }
 }

 function lookupIdentifier(ident) {
   const [lib_name, _] = ident.split('/');
   const lib = loadLibrary(lib_name);
   return lib.lookupIdentifier(ident);
 }

 /**
  * Returns the value of a given FIDL IR attribute.
  * @param {*} decl The IR containing the attribute.
  * @param {*} name The name of the attribute to return
  */
 function attribute(decl, name) {
   const attribs = decl.maybe_attributes;
   if (typeof attribs === 'undefined') {
     return;
   }
   for (const attrib of attribs) {
     if (attrib.name == name) {
       return attrib.value;
     }
   }
 }

 /**
  * Returns the fidldoc for a given method.
  * @param {*} method The IR of the method for which you want help.
  */
 function methodHelp(method) {
   let help = attribute(method, 'Doc') || '';

   function typeHelp(type) {
     switch (type.kind) {
       case 'primitive':
         return type.subtype;
       case 'string':
         return 'string' + (type.maybe_element_count ? `:${type.maybe_element_count}` : '') +
             (type.nullable ? '?' : '');
       case 'vector':
         return `vector<${typeHelp(type.element_type)}>` +
             (type.maybe_element_count ? `:${type.maybe_element_count}` : '') +
             (type.nullable ? '?' : '');
       case 'array':
         return `array<${typeHelp(type.element_type)}>:${type.element_count}` +
             (type.nullable ? '?' : '');
       case 'identifier':
         return type.identifier + (type.nullable ? '?' : '');
       case 'request':
         return `request<${type.subtype}>` + (type.nullable ? '?' : '');
       case 'handle':
         return (type.subtype === 'handle' ? 'handle' : `handle<${type.subtype}>`) +
             (type.nullable ? '?' : '');
       default:
         return `UNKNOWN(${JSON.stringify(type)})`;
     }
   }

   function argHelp(arg) {
     return `${typeHelp(arg.type)} ${arg.name}`;
   }

   function argsHelp(args) {
     return '(' + args.map(argHelp).join(', ') + ')';
   }

   help = help + method.name;

   if (method.has_request) {
     help += argsHelp(method.maybe_request);
   }

   if (method.has_response) {
     help = help + ' -> ' + argsHelp(method.maybe_response);
   }

   return help + '\n';
 }

 // Classes and libraries for communicating with FIDL services.

 const MSG_MAX_BYTES = 64 * 1024;

 /**
  * Represents a FIDL message header.
  * Given bytes representing a FIDL message, MessageHeader will provide txid and ordinal values.
  */
 class MessageHeader {
   /**
    * @param {ArrayBuffer} bytes The bytes of the message.
    */
   constructor(bytes) {
     this.buf = bytes;
     this.view = new DataView(this.buf);
     this.txid = this.view.getUint32(0, true);
     this.ordinal = this.view.getBigInt64(8, true);
   }
 };

 /**
  * Represents the client side of a protocol.
  *
  * When you construct an object of this type, methods on the protocol will
  * automatically be populated from the protocol definition.  You can then call
  * them.
  */
 class ProtocolClient {
   /**
    * Constructor for ProtocolClient.
    * @param {channel} A zx.Channel object OR an existing protocol to duplicate
    * @param {protocol} A string or a fidling object representing the protocol.
    */
   constructor(channel, protocol) {
     // Not sure if protocolName is a string or a fidling.
     if (typeof protocol === 'string' || protocol instanceof String) {
       this._protocol_name = protocol;
       let [library_name, _] = protocol.split('/');
       this._decl = loadLibrary(library_name).lookupProtocol(protocol);
     } else {
       this._protocol_name = protocol.name;
       this._decl = protocol;
     }

     // Not sure if we are being passed a channel or an existing protocol client to dup.
     if (channel instanceof zx.Channel) {
       this._impl = new ProtocolClientImpl(this._decl, channel);
     } else if ('_impl' in channel) {
       this._impl = channel._impl;
     } else {
       throw 'Illegal argument passed as channel to ProtocolClient constructor';
     }

     // Populate the ProtocolClient object with methods corresponding to the protocol methods.
     const completions = [];
     for (const method of this._decl.methods) {
       let definedProperty = false;
       if (method.has_request) {
         definedProperty = true;
         this[method.name] = (...args) => this._impl._invokeMethod(method, args);
         Object.defineProperty(this[method.name], 'length', {value: method.maybe_request.length});
       } else if (method.has_response) {
         definedProperty = true;
         this[method.name] = (fn) => this._impl._setEventProcessor(method, fn);
       }
       if (definedProperty) {
         let help = methodHelp(method);
         if (help) {
           Object.defineProperty(this[method.name], Symbol.for('help'), {value: help});
         }
         completions.push(method.name);
       }
     }
     this[Symbol.for('completions')] = completions;
   }

   /**
    * Closes the given ProtocolClient instance.
    */
   static close(protocolClient) {
     protocolClient._impl._close();
   }
 };

 // Something fidl_codec should do: when we improve the JSON output for it, this should be
 // less necessary.
 function parseFidlcatHandle(handleStr) {
   var regex = /[A-Z_]*:([0-9a-f]+)(\(.*\))?/gi;
   return parseInt(handleStr.replace(regex, '$1'), 16);
 }

 function convertResponseHandles(methodDecl, message) {
   for (let i = 0; i < methodDecl.maybe_response.length; i++) {
     if (methodDecl.maybe_response[i].type.kind == 'identifier') {
       // TODO: Look up identifier and recurse.
       continue;
     }
     if (methodDecl.maybe_response[i].type.kind == 'request') {
       const handleValue = parseFidlcatHandle(message[methodDecl.maybe_response[i].name]);
       message[methodDecl.maybe_response[i].name] = zx.Channel.fromValueDeprecated(handleValue);
     }
     if (methodDecl.maybe_response[i].type.kind == 'handle') {
       const handleValue = parseFidlcatHandle(message[methodDecl.maybe_response[i].name]);
       switch (methodDecl.maybe_response[i].type.subtype) {
         case 'job':
           message[methodDecl.maybe_response[i].name] = zx.Job.fromValueDeprecated(handleValue);
           break;
         case 'handle':
         case 'bti':
         case 'channel':
         case 'debuglog':
         case 'event':
         case 'eventpair':
         case 'exception':
         case 'fifo':
         case 'guest':
         case 'interrupt':
         case 'iommu':
         case 'pager':
         case 'pcidevice':
         case 'pmt':
         case 'port':
         case 'process':
         case 'profile':
         case 'resource':
         case 'socket':
         case 'suspendtoken':
         case 'thread':
         case 'timer':
         case 'vcpu':
         case 'vmar':
         case 'vmo':
           throw 'Unsupported handle type ' + methodDecl.maybe_response[i].type.subtype;
         default:
           throw 'Unknown handle type ' + methodDecl.maybe_response[i].type.subtype;
       }
     }
   }
   return message;
 }

 /**
  * The implementation class for the ProtocolClient.
  *
  * This prevents the messy implementation methods from being exposed to the
  * user.  Can be shared among multiple ProtocolClient objects (this is useful
  * for protocol composition, where you might have multiple protocols exposed on
  * the same channel).
  */
 class ProtocolClientImpl {
   /**
    * @param {declaration} A fidling definition for the protocol.
    * @param {channel} A zx.Channel object for communication.
    */
   constructor(declaration, channel) {
     this._decl = declaration;
     this._channel = channel;
     this._eventProcessors = new Map();  // String representing ordinal => callback on that event.
     this._txid = 1;
     this._pending = new Map();
   }
   /**
    * Returns the next transaction id for communications over this channel.
    */
   _nextTxId() {
     const txid = this._txid;
     this._txid++;
     return txid;
   }

   /**
    * Tells this client what to do when a given event is triggered.
    * @param {method} The part of the fidling describing the event.
    * @param {fn} The function to be invoked when the event happens.
    * @returns a promise that will be resolved / rejected when the event is triggered.
    */
   _setEventProcessor(method, fn) {
     this._channel.waitAsync(
         zx.ZX_CHANNEL_READABLE | zx.ZX_CHANNEL_PEER_CLOSED, () => this._readable(method));
     return new Promise((resolve, reject) => {
       if (typeof method.generated_ordinal != 'undefined') {
         this._eventProcessors.set(method.generated_ordinal, (args) => {
           try {
             resolve(fn(args));
           } catch (e) {
             reject(e);
             console.log(e);
           }
         });
       }
       this._eventProcessors.set(method.ordinal, (args) => {
         try {
           resolve(fn(args));
         } catch (e) {
           reject(e);
           console.log(e);
         }
       });
     });
   }

   /**
    * The implementation of method invocation.  The ProtocolClient methods are a
    * thin decorator around this method.  If the method takes a response, it will
    * set up an event handler to deal with the response.
    */
   _invokeMethod(method, args) {
     return new Promise((resolve, reject) => {
       try {
         let txid = 0;
         if (method.has_response) {
           this._channel.waitAsync(
               zx.ZX_CHANNEL_READABLE | zx.ZX_CHANNEL_PEER_CLOSED, () => this._readable(method));
           txid = this._nextTxId();
         }
         const encoded = internalLibrary.encodeRequest(txid, method.ordinal, args);
         if (method.has_response) {
           this._pending.set(txid, [method, resolve, reject]);
         }
         this._channel.write(encoded.bytes, encoded.handles);
         if (!method.has_response) {
           resolve();
         }  // otherwise, gets resolved when we invoke _readable.
       } catch (e) {
         console.log(e);
         console.log(e.stack);
         reject(e);
       }
     });
   }

   /**
    * Handles the response from a protocol method.  It looks up what methods
    * we're expecting a response from and tries to correlate it with the txid
    * received.
    * @param method is the FIDL IR for the method.
    */
   _readable(method) {
     const [bytes, handles] = this._channel.read();
     const header = new MessageHeader(bytes);

     let resolve = this._eventProcessors.get(header.ordinal.toString());
     if (typeof resolve == 'undefined') {
       // It's a response to a request.
       const txid = header.txid;
       if (!this._pending.has(txid)) {
         console.log(`Unexpected transaction id ${txid} from ${this._decl.name}`);
         return;
       }
       const [meth, resolve_, reject] = this._pending.get(txid);
       resolve = resolve_;
       this._pending.delete(txid);
     }
     if (typeof resolve == 'undefined') {
       throw 'Unexpected message with ordinal ' + header.ordinal + ' received';
     }
     // TODO(jeremymanson): Make sure strings in decoded response are escaped properly
     const responseString = internalLibrary.decodeResponse(bytes, handles);
     const response = convertResponseHandles(method, JSON.parse(responseString));
     resolve(response);
   }

   _close() {
     this._channel.close();
   }
 }

 /**
  * A convenience class that allows a user to say something like:
  *
  * client = new Request(fidling.fuchsia.io.Directory).getProtocolClient();
  *
  * And use client appropriately.
  */
 class Request {
   constructor(protocolIr) {
     this._protocolIr = protocolIr;
     const channels = zx.Channel.create();
     this._serverEndpoint = channels[1];
     this._clientEndpoint = channels[0];
   }

   /**
    * Generates a new ProtocolClient for this request
    */
   getProtocolClient() {
     return new fidl.ProtocolClient(this._clientEndpoint, this._protocolIr.name);
   }

   /**
    * Returns a zx.Channel representing the server endpoint for this request.
    */
   getChannelForServer() {
     return this._serverEndpoint;
   }
 };

 /**
  * Returns a ProtocolClient that connects to the server at the given path.  For example:
  * client = connectToServiceAt('/svc/fuchsia.power.BatteryManager', 'fuchsia.power/BatteryManager');
  */
 function connectToServiceAt(path, protocolName) {
   const channel = new zx.Channel(fdio.serviceConnect(path));
   return new ProtocolClient(channel, protocolName);
 }


 /**
  * Connects to a service exposed via /svc.  For example:
  * client = connectToService('fuchsia.power.BatteryManager');
  */
 function connectToService(serviceName) {
   const idx = serviceName.lastIndexOf('.');
   const name = serviceName.substr(idx + 1);
   const libraryName = serviceName.substr(0, idx);
   return connectToServiceAt(`/svc/${serviceName}`, `${libraryName}/${name}`);
 }

 global['fidl'] = {
   connectToService,
   loadLibrary,
   loadLibraryIr,
   ProtocolClient,
   Request,
 };

 function constToValue(c) {
   if (c.type.kind == 'primitive') {
     switch (c.type.subtype) {
       case 'int8':
       case 'uint8':
       case 'int16':
       case 'uint16':
       case 'int32':
       case 'uint32':
       case 'int64':
       case 'uint64':
         return parseInt(c.value.literal.value);
       case 'float32':
       case 'float64':
         return parseFloat(c.value.literal.value);
       default:
         throw 'Unknown primitive type ' + JSON.stringify(c.type) + ' ' + c.type.kind + ' ' +
             c.type.subtype;
     }
   }
 }

 // Make fidl definitions available on an object called `fidling`
 // Asking for fidling.libraryName.CONST returns a const value.
 // Asking for fidling.libraryName.Protocol returns the IR for the protocol.
 var fidling_handler = {
   get: function(obj, prop) {
     let ret = undefined;
     libraries.forEach(function(val, library, map) {
       // mangle library names to be valid JS identifiers
       const libraryName = library.replace(/\./g, '_');
       if (prop == libraryName) {
         ret = new Proxy({_name: library}, {
           get: function(library_obj, lib_prop) {
             const maybeName = library_obj._name + '/' + lib_prop;
             for (let i = 0; i < val.ir.const_declarations.length; i++) {
               let c = val.ir.const_declarations[i];
               if (c.name == maybeName) {
                 return constToValue(c);
               }
             }
             for (let i = 0; i < val.ir.interface_declarations.length; i++) {
               let p = val.ir.interface_declarations[i];
               if (p.name == maybeName) {
                 return p;
               }
             }
             // And similarly for non-const decls
             return undefined;
           }
         });
       }
     });
     return ret;
   }
 };
 const fidling = new Proxy({}, fidling_handler);

 global['fidling'] = fidling;
 })(globalThis);
	// Copyright 2019 The Fuchsia Authors. All rights reserved.
	// Use of this source code is governed by a BSD-style license that can be
	// found in the LICENSE file.

	/**
	* @fileoverview Utilities for making FIDL calls to protocols. Contains both
	* classes for interacting with FIDL definitions and for calling out to
	* services.
	*/
	import * as fidl_internal from 'fidl_internal';

	(function(global) {

	// Classes and functions for managing FIDL IR and libraries

	// TODO(jeremymanson): We really only want to look in the /pkg/ directory.
	// This involves really turning the shell into a component, which we haven't
	// done yet.
	const IR_PATH = fidl_internal.irPath;

	/**
	* Programmatic representation of a library. Contains fidling IR.
	*/
	class Library {
	constructor(ir) {
	this.ir = ir;
	this.kinds = {
	bits: this.ir.bits_declarations,
	const : this.ir.const_declarations,
	enum: this.ir.enum_declarations,
	interface: this.ir.interface_declarations,
	service: this.ir.service_declarations,
	struct: this.ir.struct_declarations,
	table: this.ir.table_declarations,
	union: this.ir.union_declarations,
	xunion: this.ir.xunion_declarations,
	type_alias: this.ir.type_alias_declarations,
	}
	}

	/**
	* Given a particular protocol name (as in FIDL IR), return the IR in this
	* library that represents that protocol.
	*/
	lookupProtocol(name) {
	const decl = this._findDeclaration(this.ir.interface_declarations, name);
	if (decl === null) {
	throw new Error(`No such protocol ${name}`);
	}
	return decl;
	}

	/**
	* Given a particular identifier name (as in FIDL IR), return the IR in this
	* library that represents that identifier.
	*/
	lookupIdentifier(ident) {
	const kind = this.ir.declarations[ident];
	return [kind, this._findDeclaration(this.kinds[kind], ident)];
	}

	_findDeclaration(decls, name) {
	for (const decl of decls) {
	if (decl.name === name) {
	return decl;
	}
	}
	return null;
	}
	};

	const libraries = new Map();
	// If we ever reassign this, we need to call close() to delete it.
	var internalLibrary = null;

	/**
	* Converts the given string to JSON, converting 64-bit ordinals to
	* strings.
	*
	* @param {String} str the string containing the IR to convert.
	*/
	function stringToJsonIr(str) {
	// Hack: replace 64-bit ordinals with strings. Better support for BigInts would be better.
	let regex = /("ordinal"\s:\s)([0-9]+)\s*,/gi;
	str = str.replace(regex, '$1"$2",');
	regex = /("generated_ordinal"\s:\s)([0-9]+)\s*,/gi;
	str = str.replace(regex, '$1"$2",');
	return JSON.parse(str);
	}

	/**
	* Loads the IR for a given library.
	* libraryName should be of the form library.protocol
	*
	* Libraries are expected to be in a directory structure such that the filename
	* is the library name, with dots replaced by directory separators, ending with
	* .fidl.json. This should be arranged by the build system.
	*/
	function loadIR(libraryName) {
	if (internalLibrary == null) {
	internalLibrary = fidl_internal.newLibrary();
	}

	let maybeSeparator = '';
	if (IR_PATH[IR_PATH.length - 1] != '/') {
	maybeSeparator = '/';
	}
	const irPath = IR_PATH + maybeSeparator + libraryName.replace(/\./g, '/') + '.fidl.json';

	// Load for JavaScript-level operations, like tab-completion and exposing the fidling.
	// We should probably move more of this to native code over time, so that we don't have to
	// load libraries twice.
	try {
	const f = std.open(irPath, 'r');
	let str = f.readAsString();
	f.close();
	let ir = stringToJsonIr(str);
	libraries.set(ir.name, new Library(ir));
	} catch {
	throw 'FIDL definition for ' + libraryName + ' not found in ' + irPath;
	}

	// Load for C++ level operations, like encoding and decoding.
	if (!internalLibrary.loadLibrary(irPath)) {
	throw 'Internal error: Unable to load libraries for ' + libraryName;
	}
	}

	/**
	* Loads the IR for a given library.
	* libraryName should be of the form library.protocol
	*
	* Libraries are expected to be in a directory structure such that the filename
	* is the library name, with dots replaced by directory separators, ending with
	* .fidl.json. This should be arranged by the build system.
	*/
	function loadLibrary(libraryName) {
	if (!libraries.has(libraryName)) {
	loadIR(libraryName);
	}
	if (!libraries.has(libraryName)) {
	throw new Error(`Could not find IR for ${libraryName}`);
	} else {
	return libraries.get(libraryName);
	}
	}

	/**
	* Loads the given string containing FIDL JSON IR as a library.
	*/
	function loadLibraryIr(irString) {
	let ir = stringToJsonIr(irString);
	if (!libraries.has(ir.name)) {
	libraries.set(ir.name, new Library(ir));
	// Load for C++ level operations, like encoding and decoding.
	if (internalLibrary == null) {
	internalLibrary = fidl_internal.newLibrary();
	}
	if (!internalLibrary.loadLibraryFromString(ir.name, JSON.stringify(ir))) {
	throw 'Internal error: Unable to load libraries for ' + ir.name;
	}
	}
	}

	function lookupIdentifier(ident) {
	const [lib_name, _] = ident.split('/');
	const lib = loadLibrary(lib_name);
	return lib.lookupIdentifier(ident);
	}

	/**
	* Returns the value of a given FIDL IR attribute.
	* @param {*} decl The IR containing the attribute.
	* @param {*} name The name of the attribute to return
	*/
	function attribute(decl, name) {
	const attribs = decl.maybe_attributes;
	if (typeof attribs === 'undefined') {
	return;
	}
	for (const attrib of attribs) {
	if (attrib.name == name) {
	return attrib.value;
	}
	}
	}

	/**
	* Returns the fidldoc for a given method.
	* @param {*} method The IR of the method for which you want help.
	*/
	function methodHelp(method) {
	let help = attribute(method, 'Doc') \|\| '';

	function typeHelp(type) {
	switch (type.kind) {
	case 'primitive':
	return type.subtype;
	case 'string':
	return 'string' + (type.maybe_element_count ? `:${type.maybe_element_count}` : '') +
	(type.nullable ? '?' : '');
	case 'vector':
	return `vector<${typeHelp(type.element_type)}>` +
	(type.maybe_element_count ? `:${type.maybe_element_count}` : '') +
	(type.nullable ? '?' : '');
	case 'array':
	return `array<${typeHelp(type.element_type)}>:${type.element_count}` +
	(type.nullable ? '?' : '');
	case 'identifier':
	return type.identifier + (type.nullable ? '?' : '');
	case 'request':
	return `request<${type.subtype}>` + (type.nullable ? '?' : '');
	case 'handle':
	return (type.subtype === 'handle' ? 'handle' : `handle<${type.subtype}>`) +
	(type.nullable ? '?' : '');
	default:
	return `UNKNOWN(${JSON.stringify(type)})`;
	}
	}

	function argHelp(arg) {
	return `${typeHelp(arg.type)} ${arg.name}`;
	}

	function argsHelp(args) {
	return '(' + args.map(argHelp).join(', ') + ')';
	}

	help = help + method.name;

	if (method.has_request) {
	help += argsHelp(method.maybe_request);
	}

	if (method.has_response) {
	help = help + ' -> ' + argsHelp(method.maybe_response);
	}

	return help + '\n';
	}

	// Classes and libraries for communicating with FIDL services.

	const MSG_MAX_BYTES = 64 * 1024;

	/**
	* Represents a FIDL message header.
	* Given bytes representing a FIDL message, MessageHeader will provide txid and ordinal values.
	*/
	class MessageHeader {
	/**
	* @param {ArrayBuffer} bytes The bytes of the message.
	*/
	constructor(bytes) {
	this.buf = bytes;
	this.view = new DataView(this.buf);
	this.txid = this.view.getUint32(0, true);
	this.ordinal = this.view.getBigInt64(8, true);
	}
	};

	/**
	* Represents the client side of a protocol.
	*
	* When you construct an object of this type, methods on the protocol will
	* automatically be populated from the protocol definition. You can then call
	* them.
	*/
	class ProtocolClient {
	/**
	* Constructor for ProtocolClient.
	* @param {channel} A zx.Channel object OR an existing protocol to duplicate
	* @param {protocol} A string or a fidling object representing the protocol.
	*/
	constructor(channel, protocol) {
	// Not sure if protocolName is a string or a fidling.
	if (typeof protocol === 'string' \|\| protocol instanceof String) {
	this._protocol_name = protocol;
	let [library_name, _] = protocol.split('/');
	this._decl = loadLibrary(library_name).lookupProtocol(protocol);
	} else {
	this._protocol_name = protocol.name;
	this._decl = protocol;
	}

	// Not sure if we are being passed a channel or an existing protocol client to dup.
	if (channel instanceof zx.Channel) {
	this._impl = new ProtocolClientImpl(this._decl, channel);
	} else if ('_impl' in channel) {
	this._impl = channel._impl;
	} else {
	throw 'Illegal argument passed as channel to ProtocolClient constructor';
	}

	// Populate the ProtocolClient object with methods corresponding to the protocol methods.
	const completions = [];
	for (const method of this._decl.methods) {
	let definedProperty = false;
	if (method.has_request) {
	definedProperty = true;
	this[method.name] = (...args) => this._impl._invokeMethod(method, args);
	Object.defineProperty(this[method.name], 'length', {value: method.maybe_request.length});
	} else if (method.has_response) {
	definedProperty = true;
	this[method.name] = (fn) => this._impl._setEventProcessor(method, fn);
	}
	if (definedProperty) {
	let help = methodHelp(method);
	if (help) {
	Object.defineProperty(this[method.name], Symbol.for('help'), {value: help});
	}
	completions.push(method.name);
	}
	}
	this[Symbol.for('completions')] = completions;
	}

	/**
	* Closes the given ProtocolClient instance.
	*/
	static close(protocolClient) {
	protocolClient._impl._close();
	}
	};

	// Something fidl_codec should do: when we improve the JSON output for it, this should be
	// less necessary.
	function parseFidlcatHandle(handleStr) {
	var regex = /[A-Z_]:([0-9a-f]+)(\(.\))?/gi;
	return parseInt(handleStr.replace(regex, '$1'), 16);
	}

	function convertResponseHandles(methodDecl, message) {
	for (let i = 0; i < methodDecl.maybe_response.length; i++) {
	if (methodDecl.maybe_response[i].type.kind == 'identifier') {
	// TODO: Look up identifier and recurse.
	continue;
	}
	if (methodDecl.maybe_response[i].type.kind == 'request') {
	const handleValue = parseFidlcatHandle(message[methodDecl.maybe_response[i].name]);
	message[methodDecl.maybe_response[i].name] = zx.Channel.fromValueDeprecated(handleValue);
	}
	if (methodDecl.maybe_response[i].type.kind == 'handle') {
	const handleValue = parseFidlcatHandle(message[methodDecl.maybe_response[i].name]);
	switch (methodDecl.maybe_response[i].type.subtype) {
	case 'job':
	message[methodDecl.maybe_response[i].name] = zx.Job.fromValueDeprecated(handleValue);
	break;
	case 'handle':
	case 'bti':
	case 'channel':
	case 'debuglog':
	case 'event':
	case 'eventpair':
	case 'exception':
	case 'fifo':
	case 'guest':
	case 'interrupt':
	case 'iommu':
	case 'pager':
	case 'pcidevice':
	case 'pmt':
	case 'port':
	case 'process':
	case 'profile':
	case 'resource':
	case 'socket':
	case 'suspendtoken':
	case 'thread':
	case 'timer':
	case 'vcpu':
	case 'vmar':
	case 'vmo':
	throw 'Unsupported handle type ' + methodDecl.maybe_response[i].type.subtype;
	default:
	throw 'Unknown handle type ' + methodDecl.maybe_response[i].type.subtype;
	}
	}
	}
	return message;
	}

	/**
	* The implementation class for the ProtocolClient.
	*
	* This prevents the messy implementation methods from being exposed to the
	* user. Can be shared among multiple ProtocolClient objects (this is useful
	* for protocol composition, where you might have multiple protocols exposed on
	* the same channel).
	*/
	class ProtocolClientImpl {
	/**
	* @param {declaration} A fidling definition for the protocol.
	* @param {channel} A zx.Channel object for communication.
	*/
	constructor(declaration, channel) {
	this._decl = declaration;
	this._channel = channel;
	this._eventProcessors = new Map(); // String representing ordinal => callback on that event.
	this._txid = 1;
	this._pending = new Map();
	}
	/**
	* Returns the next transaction id for communications over this channel.
	*/
	_nextTxId() {
	const txid = this._txid;
	this._txid++;
	return txid;
	}

	/**
	* Tells this client what to do when a given event is triggered.
	* @param {method} The part of the fidling describing the event.
	* @param {fn} The function to be invoked when the event happens.
	* @returns a promise that will be resolved / rejected when the event is triggered.
	*/
	_setEventProcessor(method, fn) {
	this._channel.waitAsync(
	zx.ZX_CHANNEL_READABLE \| zx.ZX_CHANNEL_PEER_CLOSED, () => this._readable(method));
	return new Promise((resolve, reject) => {
	if (typeof method.generated_ordinal != 'undefined') {
	this._eventProcessors.set(method.generated_ordinal, (args) => {
	try {
	resolve(fn(args));
	} catch (e) {
	reject(e);
	console.log(e);
	}
	});
	}
	this._eventProcessors.set(method.ordinal, (args) => {
	try {
	resolve(fn(args));
	} catch (e) {
	reject(e);
	console.log(e);
	}
	});
	});
	}

	/**
	* The implementation of method invocation. The ProtocolClient methods are a
	* thin decorator around this method. If the method takes a response, it will
	* set up an event handler to deal with the response.
	*/
	_invokeMethod(method, args) {
	return new Promise((resolve, reject) => {
	try {
	let txid = 0;
	if (method.has_response) {
	this._channel.waitAsync(
	zx.ZX_CHANNEL_READABLE \| zx.ZX_CHANNEL_PEER_CLOSED, () => this._readable(method));
	txid = this._nextTxId();
	}
	const encoded = internalLibrary.encodeRequest(txid, method.ordinal, args);
	if (method.has_response) {
	this._pending.set(txid, [method, resolve, reject]);
	}
	this._channel.write(encoded.bytes, encoded.handles);
	if (!method.has_response) {
	resolve();
	} // otherwise, gets resolved when we invoke _readable.
	} catch (e) {
	console.log(e);
	console.log(e.stack);
	reject(e);
	}
	});
	}

	/**
	* Handles the response from a protocol method. It looks up what methods
	* we're expecting a response from and tries to correlate it with the txid
	* received.
	* @param method is the FIDL IR for the method.
	*/
	_readable(method) {
	const [bytes, handles] = this._channel.read();
	const header = new MessageHeader(bytes);

	let resolve = this._eventProcessors.get(header.ordinal.toString());
	if (typeof resolve == 'undefined') {
	// It's a response to a request.
	const txid = header.txid;
	if (!this._pending.has(txid)) {
	console.log(`Unexpected transaction id ${txid} from ${this._decl.name}`);
	return;
	}
	const [meth, resolve_, reject] = this._pending.get(txid);
	resolve = resolve_;
	this._pending.delete(txid);
	}
	if (typeof resolve == 'undefined') {
	throw 'Unexpected message with ordinal ' + header.ordinal + ' received';
	}
	// TODO(jeremymanson): Make sure strings in decoded response are escaped properly
	const responseString = internalLibrary.decodeResponse(bytes, handles);
	const response = convertResponseHandles(method, JSON.parse(responseString));
	resolve(response);
	}

	_close() {
	this._channel.close();
	}
	}

	/**
	* A convenience class that allows a user to say something like:
	*
	* client = new Request(fidling.fuchsia.io.Directory).getProtocolClient();
	*
	* And use client appropriately.
	*/
	class Request {
	constructor(protocolIr) {
	this._protocolIr = protocolIr;
	const channels = zx.Channel.create();
	this._serverEndpoint = channels[1];
	this._clientEndpoint = channels[0];
	}

	/**
	* Generates a new ProtocolClient for this request
	*/
	getProtocolClient() {
	return new fidl.ProtocolClient(this._clientEndpoint, this._protocolIr.name);
	}

	/**
	* Returns a zx.Channel representing the server endpoint for this request.
	*/
	getChannelForServer() {
	return this._serverEndpoint;
	}
	};

	/**
	* Returns a ProtocolClient that connects to the server at the given path. For example:
	* client = connectToServiceAt('/svc/fuchsia.power.BatteryManager', 'fuchsia.power/BatteryManager');
	*/
	function connectToServiceAt(path, protocolName) {
	const channel = new zx.Channel(fdio.serviceConnect(path));
	return new ProtocolClient(channel, protocolName);
	}


	/**
	* Connects to a service exposed via /svc. For example:
	* client = connectToService('fuchsia.power.BatteryManager');
	*/
	function connectToService(serviceName) {
	const idx = serviceName.lastIndexOf('.');
	const name = serviceName.substr(idx + 1);
	const libraryName = serviceName.substr(0, idx);
	return connectToServiceAt(`/svc/${serviceName}`, `${libraryName}/${name}`);
	}

	global['fidl'] = {
	connectToService,
	loadLibrary,
	loadLibraryIr,
	ProtocolClient,
	Request,
	};

	function constToValue(c) {
	if (c.type.kind == 'primitive') {
	switch (c.type.subtype) {
	case 'int8':
	case 'uint8':
	case 'int16':
	case 'uint16':
	case 'int32':
	case 'uint32':
	case 'int64':
	case 'uint64':
	return parseInt(c.value.literal.value);
	case 'float32':
	case 'float64':
	return parseFloat(c.value.literal.value);
	default:
	throw 'Unknown primitive type ' + JSON.stringify(c.type) + ' ' + c.type.kind + ' ' +
	c.type.subtype;
	}
	}
	}

	// Make fidl definitions available on an object called `fidling`
	// Asking for fidling.libraryName.CONST returns a const value.
	// Asking for fidling.libraryName.Protocol returns the IR for the protocol.
	var fidling_handler = {
	get: function(obj, prop) {
	let ret = undefined;
	libraries.forEach(function(val, library, map) {
	// mangle library names to be valid JS identifiers
	const libraryName = library.replace(/\./g, '_');
	if (prop == libraryName) {
	ret = new Proxy({_name: library}, {
	get: function(library_obj, lib_prop) {
	const maybeName = library_obj._name + '/' + lib_prop;
	for (let i = 0; i < val.ir.const_declarations.length; i++) {
	let c = val.ir.const_declarations[i];
	if (c.name == maybeName) {
	return constToValue(c);
	}
	}
	for (let i = 0; i < val.ir.interface_declarations.length; i++) {
	let p = val.ir.interface_declarations[i];
	if (p.name == maybeName) {
	return p;
	}
	}
	// And similarly for non-const decls
	return undefined;
	}
	});
	}
	});
	return ret;
	}
	};
	const fidling = new Proxy({}, fidling_handler);

	global['fidling'] = fidling;
	})(globalThis);