A firebase web platform
``
npm install h1v3
e.g. /h1v3.paths.js
`javascript${root}/teams/$tid
const root = "/h1v3";
const teamPath = ;${root}/users/$uid
const userPath = ;
const h1v3 = {
team: {
membership: {
path: ${teamPath}/membership
},
details: {
path:
},
},
user: {
teams: {
path:
},
profile: {
path:
}
},
userInvites: {
path:
},
o11y: {
path:
}
};
h1v3.team.documents = {
path: ${teamPath}/data/$did
};
export default h1v3;
`
e.g. functions/index.js
`javascript
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
});
`
e.g. firebase.json
`json`
{
. . .
"hosting": {
. . .
"rewrites": [
{
"source": "/store_meta",
"function": {
"functionId": "store_meta",
"region": "europe-west1"
}
}
]
},
. . .
}
This allows you to, in the browser, do:
`javascript`
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
You can vendor the (free) dependencies and client files for the library using npx
`bash`
npx h1v3 vendor-deps
npx h1v3 vendor-client
This will create folders such as:
- /public/vendor/h1v3@0.7.6 (see below for suggestion on isolating your code from the library version)/public/vendor/lit@3.3.1
- (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.
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
`javascript`
export { default as bus } from "/vendor/h1v3@0.7.6/client/bus.js";
export { EVENT_USER_PROFILE_CHANGED } from "/vendor/h1v3@0.7.6/client/events.js";
export { styled } from "/vendor/h1v3@0.7.6/client/components/partials/wa-utils.js";
export * from "/vendor/h1v3@0.7.6/client/system.js";
The system expects you to expose your (public) firebase config in an ESM module at /firebase.config.js. For example:
`javascript`
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"
};
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).
`javascript
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):
`javascript`
export * from "h1v3.config.js";
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.
`javascript`
export default {
name: String,
age: Number,
favourite: {
color: String
}
};
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:
`javascript
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));
}
}
];
}
`
Once you have defined your configuration (h1v3.config.js) you can generate your databse.rules.json file:`sh``
cd functions
npx h1v3 rules --output ../database.rules.json
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