h1v3

A firebase web platform

Install

npm install h1v3

Meta data

Define your store paths

e.g. /h1v3.paths.js

const root = "/h1v3";
const teamPath = `${root}/teams/$tid`;
const userPath = `${root}/users/$uid`;

const h1v3 = {
    team: {
        membership: {
            path: `${teamPath}/membership`
        },
        details: {
            path: `${teamPath}/details`
        },
    },
    user: {
        teams: {
            path: `${userPath}/teams`
        },
        profile: {
            path: `${userPath}/profile`
        }
    },
    userInvites: {
        path: `${root}/user-invites/$emailId`
    },
    o11y: {
        path: `${root}/o11y/$id`
    }
};

h1v3.team.documents = {
    path: `${teamPath}/data/$did`
};

export default h1v3;

Register metadata endpoint

e.g. functions/index.js

import { setGlobalOptions } from "firebase-functions";
import { configureMetadataEndpoint } from "h1v3";
import { onRequest } from "firebase-functions/https";
import * as h1v3Config from "./h1v3.config.js";
import paths from "./h1v3.paths.js";

setGlobalOptions({ maxInstances: 10 });

export * from "./h1v3.config.js";

export const store_meta = configureMetadataEndpoint({

    module: h1v3Config,
    paths,
    region: h1v3Config.region,
    onRequest

});

(Optional) register a redirect for firebase hosting

e.g. firebase.json

{
  . . .
  "hosting": {
    . . .
    "rewrites": [
      {
        "source": "/store_meta",
        "function": {
          "functionId": "store_meta",
          "region": "europe-west1"
        }
      }
    ]
  },
  . . .
}

This allows you to, in the browser, do:

const meta = import("/store_meta") with { type: "json" }

[!CAUTION] At time of writing, the firebase emulators don't properly support the use of RTDB and triggers outside of the us-central1 region. This is a problem if you are deploying to production based on a firebase.json.

For that reason, you many need to use us-central1 as your "default" firebase.json entry, and replace it at deploy time. For example, using:

cat firebase.json | jq "(.hosting.rewrites.[] | select(.source == \"/store_meta\") | .function) += { region: \"europe-west1\" }" > firebase.json.

IKR

Client-side libraries

You can vendor the (free) dependencies and client files for the library using npx

npx h1v3 vendor-deps
npx h1v3 vendor-client

This will create folders such as:

• /public/vendor/[email protected] (see below for suggestion on isolating your code from the library version)
• /public/vendor/[email protected] (see https://lit.dev/)

You will also need to provide a vendored library of WebAwesome Pro:

• /public/vendor/webawesome-pro - for now this is an explicit dependency although you can symlink it to your current version of webawesome-pro. The system expects the dist folder to be available at /public/vendor/webawesome-pro/dist.

Usage patterns - Client-side

Importing the library

When using the library in your website, you may wish to create a single import location which isolates your code from the version of h1v3 you are using. You can also use it to explicitly declare which bits of the library you are depending upon.

e.g. /public/js/h1v3.js

export { default as bus } from "/vendor/[email protected]/client/bus.js";
export { EVENT_USER_PROFILE_CHANGED } from "/vendor/[email protected]/client/events.js";
export { styled } from "/vendor/[email protected]/client/components/partials/wa-utils.js";
export * from "/vendor/[email protected]/client/system.js";

Firebase configuration

The system expects you to expose your (public) firebase config in an ESM module at /firebase.config.js. For example:

export default {
    apiKey: "AIzaSyCV6FjdJwU50TUZVRcoFCWqQItjhhQKbXQ",
    authDomain: "ixion-c9e0e.firebaseapp.com",
    databaseURL: "https://ixion-c9e0e-default-rtdb.europe-west1.firebasedatabase.app",
    projectId: "ixion-c9e0e",
    appId: "1:28699144755:web:2ab262d02ccba70979e946"
};

Usage Patterns - Firebase functions

Basic routes

Configure at least the following four event stores:

• user_profile - in which a user can maintain details of their profile (as determined by the referenced schema)
• user_teams - where the system will maintain a quick lookup list of a user's teams
• team_membership - where the system records the master list of users' membership of teams, and their role (member or admin)
• team_details - where any admin of a team can maintain details of the team they administer (as determined by the referenced schema).

import { onValueWritten } from "firebase-functions/database";

import * as h1v3 from "h1v3";

import paths from "./h1v3.paths.js";
import userProfileSchema from "./schemas/user-profile-schema.js";
import teamDetailsSchema from "./schemas/team-details-schema.js";
import { observe } from "./o11y-provider.js";
import { region, rtdbInstance } from "./firebase.config.js";


const configureEventStore = h1v3.configureEventStore.inject({
    region,
    onValueWritten,
    instance: rtdbInstance,
    paths,
    observe,
});

export const user_profile = configureEventStore(h1v3.userProfile.store, userProfileSchema);
export const user_teams = configureEventStore(h1v3.userTeams.store);
export const team_membership = configureEventStore(h1v3.teamMembership.store);
export const team_details = configureEventStore(h1v3.teamDetails.store, teamDetailsSchema);

I usually put these in a file called "h1v3.config.js" and then remember to export these from my top-level index.js (as shown above):

export * from "h1v3.config.js";

Defining schemas

Schemas for the two built-in event stores user_profile and team_details expect a schema defined using a javascript prototype as shown below. Note that there is no required constraint. Instead the schema is a white-list of keys along with the expected type for the associated value.

export default {
    name: String,
    age: Number,
    favourite: {
        color: String
    }
};

Observability provider

h1v3 has a built-in observability provider, but it must be initialised using external logging and trace facilities. An example implementation is shown below. This illustrates initialising the provider with (1) emulated versions of tracing and logging and (2) Google Cloud versions:

import { Logging } from "@google-cloud/logging";
import { google } from "googleapis";

import * as h1v3 from "h1v3";

import { projectId, serviceName } from "./firebase.config.js";

const [trace, log] = process.env.FUNCTIONS_EMULATOR === "true" ? buildEmulated() : buildReal();

export const observe = h1v3.o11y.provider({
    trace,
    log,
    projectId,
    serviceName
});

function buildReal() {

    const scopes = [
        "https://www.googleapis.com/auth/trace.append",
        "https://www.googleapis.com/auth/cloud-platform"
    ];

    google.auth.getClient({ scopes }).then(auth => google.options({ auth })); // we can't await this as firebase will complain

    return [
        google.cloudtrace("v2"),
        new Logging().log(serviceName)
    ];

}

function buildEmulated() {

    return [
        {
            projects: {
                traces: {
                    spans: {
                        createSpan(...args) {

                            console.log("[TRACE]", JSON.stringify(args));

                        }
                    }
                }
            }
        },
        {
            entry: (...args) => args,
            write(entry) {

                console.log("[LOG]", JSON.stringify(entry));

            }
        }
    ];

}

Database rules

Once you have defined your configuration (h1v3.config.js) you can generate your databse.rules.json file:

cd functions
npx h1v3 rules --output ../database.rules.json

Implicit Google API dependencies

Note - this is an incomplete list...

• Firebase (various APIs)
• Cloud Functions API
• Cloud Resource Manager API
• Cloud Run Admin API
• Eventarc API
• IAM Service Account Credentials API
• Security Token Service API