Skip to content

Commit

Permalink
feat(core-api): common consortium interface
Browse files Browse the repository at this point in the history 
Signed-off-by: jordigiam <[email protected]>
  • Loading branch information
@petermetz
jordigiam authored and petermetz committed Mar 9, 2021
1 parent e8302a1 commit aa070ad
Show file tree
Hide file tree
Showing 2 changed files with 28 additions and 0 deletions.
27 changes: 27 additions & 0 deletions packages/cactus-core-api/src/main/typescript/plugin/consortium/i-plugin-consortium.ts
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
import { ICactusPlugin } from "../i-cactus-plugin";

/**
* Common interface to be implemented by plugins which are implementing the connection to ledgers.
*/
export interface IPluginConsortium<
GetNodeJwsIn,
GetNodeJwsOut,
GetConsortiumJwsIn,
GetConsortiumJwsOut
> extends ICactusPlugin {
/**
* Returns the JSON Web Signature of the consortium metadata, as issued by the
* **current node** that the request has been issued to.
* @param req The parameters of the request, if any.
*/
getNodeJws(req?: GetNodeJwsIn): Promise<GetNodeJwsOut>;

/**
* Returns the JSON Web Signature of the consortium metadata, as issued by
* **all the nodes in the consortium** that are known to be in the consortium
* by this current node that the request has been issued to.
*
* @param req The parameters of the request, if any.
*/
getConsortiumJws(req?: GetConsortiumJwsIn): Promise<GetConsortiumJwsOut>;
}
1 change: 1 addition & 0 deletions packages/cactus-core-api/src/main/typescript/public-api.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ export * from "./generated/openapi/typescript-axios/index";
export * from "./generated/openapi/typescript-axios/base";

export { IPluginLedgerConnector } from "./plugin/ledger-connector/i-plugin-ledger-connector";
export { IPluginConsortium } from "./plugin/consortium/i-plugin-consortium";
export { IPluginKeychain } from "./plugin/keychain/i-plugin-keychain";
export { IExpressRequestHandler } from "./plugin/web-service/i-express-request-handler";

Expand Down

2 comments on commit aa070ad

@RafaelAPB
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why do we need to bind JWTs to the consortium management? Shouldn't we keep it flexible?

@petermetz
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why do we need to bind JWTs to the consortium management? Shouldn't we keep it flexible?

@RafaelAPB Thought about it and I agree.
We kind of already took an initial step with the generic type parameters allowing to plugin to return anything there as a response, but the method names have JWS hard coded in them so it's inconsistent at the moment because it's technically already possible to return anything else other than a JWS but the method name makes it confusing.
There could be a "format" parameter in the request object definition that could be an enumeration of possible values like X.509, JWS, etc and then the return value depends on what was passed in there, BUT personally I'd prefer to have single purpose methods (a software eng. practice I like very much) with the format hard-coded in the name, something like this maybe? (See below, just added 2 extra methods as an example for X509).

To this you could say that it's still not fully dynamic, and to that I will say that people still have the ability to implement additional endpoints on their consortium plugin implementations for any exotic/completely custom signature schemes, but what's in the core-api interface definition is the recipe for a recommended minimum viable implementation that the majority of the users/operators should be satisfied/compatible with. So there is a little bit of an opinion in there and I'm hoping that it's just enough to help shepherd everyone in roughly the same direction but at the same time there's flexibility because on top of this your consortium plugin can implement any number of additional methods and if your users of that plugin really need that they'll just need to do a type casting (and I'd rather push that type casting to happen on the higher level code using cactus versus Cactus doing those type castings internally which is what would happen if we had a fully dynamic method). This is getting long so I'll stop typing, but wanted to make sure that my state of mind/thoughts are expressed in detail instead of just saying something "well I prefer it this or that way" so that we can get to the meat of the discussion.

export interface IPluginConsortium<
  GetNodeJwsIn,
  GetNodeJwsOut,
  GetConsortiumJwsIn,
  GetConsortiumJwsOut
> extends ICactusPlugin {
  /**
   * Returns the JSON Web Signature of the consortium metadata, as issued by the
   * **current node** that the request has been issued to.
   * @param req The parameters of the request, if any.
   */
  getNodeJws(req?: GetNodeJwsIn): Promise<GetNodeJwsOut>;

  /**
   * Returns the JSON Web Signature of the consortium metadata, as issued by
   * **all the nodes in the consortium** that are known to be in the consortium
   * by this current node that the request has been issued to.
   *
   * @param req The parameters of the request, if any.
   */
  getConsortiumJws(req?: GetConsortiumJwsIn): Promise<GetConsortiumJwsOut>;

  getNodeX509(req?: GetNodeX509In): Promise<GetNodeX509Out>;
  getConsortiumX509(req?: GetConsortiumX509In): Promise<GetConsortiumX509Out>;
}

And then implementing these would be optional for the consortium plugin in the sense that if you only want your plugin to do JWS you can throw back an HTTP status code of 501 NOT_IMPLEMENTED https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/501

Nitpicking: it's RFC 7515 [1] JWS not JWT (but they are very close to each other so this changes nothing with regards your question)
[1]: https://tools.ietf.org/html/rfc7515

Please sign in to comment.