Model, AbstractModel and buffers.

[alexandercerutti]

I was reasoning on the core concepts that compose passkit-generator and comparing them against other libraries.
One of the core concepts regards the creation of model.

In the current situation, passkit-generator allows creating a pass starting from:

• A set of buffers, each linked to a file name
• A model saved in the file system
• Abstract model

I always thought that passkit-generator should have not allowed users to create runtime models. And maybe this could be one of the reasons for which other libraries might get chosen.

When I created v2.0, I thought that PG might have run in two different contexts that have Node.JS APIs:

• Personal server application, which is usually always active
• Cloud Functions (like AWS Lambdas), which get activated when "pinged".

Now, when talking about the first case, the library is kept loaded and the application can load the model in any way the developer wants.
But when talking about the second case, the library must be reloaded if we have cold-starts. So the possible ways to create the model here are:

• creating runtime
• reading from buckets / file system before running the creation
• reading from buckets through the integrated feature (is it possible? Are buckets accessible through fs API?)

Having a bucket or any similar concept may cost, so maybe the first approach might be preferred when developing a cloud function.

I must add that I actually don't know how many of you are using AbstractModel to keep data in memory and if you consider it useful for your implementations.

So I was thinking about a refactor, to be implemented in v3, concerning model concepts we have in the current situation.
My idea was to "merge" all of them in... maybe one class?

These are the core points a model should do:

1. Be kept in memory (currently Abstract Model take care of this);
2. Be created from the file system;
3. Be cloned and reused;
4. Be created from a buffer list;
5. Be completed in a future moment of application runtime;
6. Be directly immutable and follow a functional approach (I'd like to);

So we could have a class that could be used like this / have this signature for example:

// signature
Model.fromFs(path: string): Model;
// usage
const model = Model.fromFs(modelFolderPath);

// signature
constructor(bufferList: { [path: string]: Buffer }): Model;
// usage
const model = new Model({
    "file.png": Buffer.alloc(0),
});

// signature
Model.clone(source: Model): Model;
// usage
const newModel = Model.clone(oldModel);

Having such a class that allows a Model to be built through a buffer list, would allow the developer to create a template in runtime I guess. We could also allow pass.json to be passed as a buffer, string, or JSON object.

Would also be useful for the Model instance to be "closed" or "destroyed" to avoid it being used again?

Let me know.
Thank you for the feedback.

[alexandercerutti]

@ianbale @neogucky @Dicondur @moogus

May I have feedback from you please?
I'm tagging you because I know you are using passkit-generator in cloud functions if I'm not mistaken.

Thank you very much!

[alexandercerutti]

@ianbale This seems to be more a request of help than a thought on what I was reasoning on. 😄
You should debug it through the guide in the wiki I wrote and then, in case, opening an issue.

[ianbale]

I don't think using cloud really needs anything different to a personal server setup. File based data works just the same and almost certainly instantiates more quickly than having the model / files externally and collecting them at run time.

You mention storing models in buckets. Whilst it may be convenient to specify a bucket name to passkit-generator and let it collect the data it seems to me to be outside of the scope. I'd stick to expecting users to simply provide the model data in an object. It is up to them to store it where it best suits them and use their own code to collect it before initialising passkit-generator.

Q: Why does pass.json need to be a Buffer rather than just an object?
I can see why images would need to be in a buffer form, but why the json?

For my use case, I have the bare minimum in the model. Just about everything in injected at runtime from dynamic data.

{
  "formatVersion": 1,
  "organizationName": "Smartix",
  "passTypeIdentifier": "pass.com.hazardousfrog.rail",
  "serialNumber": "placeholder",
  "teamIdentifier": "54GQCP5JCQ",
  "description": "placeholder",
  "groupingIdentifier" : "placeholder",
  "logoText": "placeholder",
  "foregroundColor" : "rgb(0, 0, 0)",
  "backgroundColor" : "rgb(255, 248, 0)",
  "labelColor" : "rgb(121, 121, 121)",
  "boardingPass": {}
}

However, I can see no reason why it should not be permitted. I can certainly imagine a use-case for a general purpose pass generation service that might need to create this on the fly from request data.

[alexandercerutti]

I'd stick to expecting users to simply provide the model data in an object. It is up to them to store it where it best suits them and use their own code to collect it before initialising passkit-generator.

I said "buckets" but actually, I don't know very well that world. So I quoted buckets because I think people may want to store models in them, and maybe querying them might cost. So, it actually depends on the adopted strategy and architecture.

Q: Why does pass.json need to be a Buffer rather than just an object?

I always saw all the files coming from the model as "files from the file system". So I read them and use them without expecting anyone to change them. Also, programmatically talking, it is easier to know that you are receiving just one format of files instead of two or more.

For this reason, I added the property overrides, so you can add and replace properties in pass.json.
We might reason on this to understand if there's a margin of improvement.

[sarawarnock]

Hi All - I used this model and it worked great for me. I used JSON.stringify(pass.json) for my pass object. I had to play around with it a bit and be sure to include both the thumbnail and the icon. Hope this is helpful for someone!

const pass = JSON.stringify({
          "formatVersion" : 1,
          "passTypeIdentifier" : "//////",
          "serialNumber" : "//////",
          "webServiceURL" : "https://example.com/passes/",
          "authenticationToken" : "////////",
          "teamIdentifier" : "//////",
          "organizationName" : "//////",
          "description" : "Pass",
          "logoText" : "Example Pass",
          "foregroundColor" : "rgb(255, 225, 255)",
          "backgroundColor" : "rgb(3, 90, 252)",
            "primaryFields" : [
              {
                "key" : "name",
                "label" : "Name of Person",
                "value" : "Alice Scott"
              }
            ],
            "auxiliaryFields" : [
              {
                "key": "validUntil",
                "label": "Expires",
                "value": "10 May 2022"
              }
            ],
            "backFields" : [
              {
                "key" : "example",
                "label" : "example",
                "value" : "example"
              },
            ]
          }
      }
   )

const img = fs.readFileSync("./folder/icon.png", "base64")
        const examplePass = await createPass({
            model: {
                "thumbnail.png": Buffer.from(img, 'base64'),
                "icon.png": Buffer.from(img, 'base64'),
	        "pass.json": Buffer.from(pass, 'utf-8'),
            },
            certificates: {
                wwdr: "./certs/wwdr.pem",
                signerCert: "./certs/signercert.pem",
                signerKey: {
                    keyFile: "./certs/signerkey.pem",
                    passphrase: "// random string"
                }
            }
        });

[alexandercerutti]

The latest version, v3.0, includes changes that include this topic. If you have a chance to try it, let me know what you think about it and if it solves some problems.