@toa.io/extensions.chronicles 0.0.0-stage → 1.0.0-alpha.332

package/components/chronicles.facts/manifest.toa.yaml

@@ -0,0 +1,32 @@
+namespace: chronicles
+name: facts
+
+# The extension writes what this component is sent to the log.
+chronicles: ~
+
+operations:
+  record:
+    type: effect
+    input:
+      description: A fact a component sent, as the row it is written as
+      type: object
+      properties:
+        id:
+          type: string
+        label:
+          type: string
+        component:
+          type: string
+        time:
+          type: integer
+        entity:
+          type: "null"
+        version:
+          type: "null"
+        identity:
+          type: [string, "null"]
+        trace:
+          type: [string, "null"]
+        payload:
+          type: object
+      required: [id, label, component, time, payload]

package/components/chronicles.facts/operations/record.js

@@ -0,0 +1,4 @@
+// a fact a component sent with `context.chronicles.send`, written by the extension
+export async function effect(input, context) {
+  await context.chronicles.record(input)
+}

package/components/chronicles.facts/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from './toa.d.ts'
+
+// What a manifest does not state belongs here, and every run keeps it.

package/components/chronicles.facts/types/toa.d.ts

@@ -0,0 +1,19 @@
+// Written by `toa types`. Every run rewrites it.
+// What a manifest does not state belongs in a file of your own.
+
+
+export type RecordInput = {
+  id: string
+  label: string
+  component: string
+  time: number
+  entity?: null
+  version?: null
+  identity?: string | null
+  trace?: string | null
+  payload: Record<string, unknown>
+}
+
+export interface Component {
+  record: (request: { input: RecordInput, task?: boolean }) => Promise<unknown>
+}

package/components/chronicles.ingestion/manifest.toa.yaml

@@ -0,0 +1,60 @@
+namespace: chronicles
+name: ingestion
+
+# The extension writes what this component is sent to the log, under `agent.`
+chronicles: ~
+
+operations:
+  anonymous:
+    type: effect
+    input: &batch
+      description: >
+        `{ events }`, at most 100 of them, each `{ id, name, time, payload? }`, and the client's
+        `ip` and `country`, which the gateway puts in; as JSON, or as the form
+        `navigator.sendBeacon` sends, whose `events` is their JSON, which the extension parses
+        and checks
+      type: object
+    output: &accepted
+      type: object
+      properties:
+        status:
+          type: integer
+        accepted:
+          type: integer
+    errors: &errors [INVALID, OVERSIZED]
+  identified:
+    type: effect
+    input: *batch
+    output: *accepted
+    errors: *errors
+
+exposition:
+  isolated: true
+  /:
+    POST:
+      anonymous: true
+      map:ip: ip
+      map:country: country
+      io:throttle:
+        key: [ip]
+        requests: 60
+        interval: 60
+      io:status: status
+      io:output: [status, accepted]
+      help:method: null
+      endpoint: anonymous
+  /:identity:
+    POST:
+      auth:id: identity
+      map:segments:
+        identity: identity
+      map:ip: ip
+      map:country: country
+      io:throttle:
+        key: [identity]
+        requests: 60
+        interval: 60
+      io:status: status
+      io:output: [status, accepted]
+      help:method: null
+      endpoint: identified

package/components/chronicles.ingestion/operations/anonymous.js

@@ -0,0 +1,4 @@
+// what anyone sent, checked and written by the extension
+export async function effect(input, context) {
+  return await context.chronicles.ingest(input, null)
+}

package/components/chronicles.ingestion/operations/identified.js

@@ -0,0 +1,4 @@
+// what a caller the gateway verified sent, written as that identity's
+export async function effect(input, context) {
+  return await context.chronicles.ingest(input, input.identity)
+}

package/components/chronicles.ingestion/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from './toa.d.ts'
+
+// What a manifest does not state belongs here, and every run keeps it.

package/components/chronicles.ingestion/types/toa.d.ts

@@ -0,0 +1,23 @@
+// Written by `toa types`. Every run rewrites it.
+// What a manifest does not state belongs in a file of your own.
+
+import type { CodedError } from '@toa.io/core/types'
+
+export type AnonymousInput = Record<string, unknown>
+
+export type AnonymousOutput = {
+  status?: number
+  accepted?: number
+}
+
+export type IdentifiedInput = Record<string, unknown>
+
+export type IdentifiedOutput = {
+  status?: number
+  accepted?: number
+}
+
+export interface Component {
+  anonymous: (request: { input: AnonymousInput, task?: boolean }) => Promise<AnonymousOutput | CodedError<"INVALID" | "OVERSIZED">>
+  identified: (request: { input: IdentifiedInput, task?: boolean }) => Promise<IdentifiedOutput | CodedError<"INVALID" | "OVERSIZED">>
+}

package/components/chronicles.queries/manifest.toa.yaml

@@ -0,0 +1,115 @@
+namespace: chronicles
+name: queries
+
+# The extension puts the log's reader on this component.
+chronicles: ~
+
+operations:
+  describe:
+    type: computation
+    output:
+      type: object
+      properties:
+        dialect:
+          description: What a query is written in
+          type: string
+        labels:
+          type: array
+        states:
+          type: array
+        views:
+          type: array
+  query:
+    type: computation
+    input:
+      type: object
+      properties:
+        sql:
+          description: One statement over the log, in the dialect `describe` names
+          type: string
+          minLength: 1
+          maxLength: 65536
+      required: [sql]
+    output:
+      type: object
+      properties:
+        columns:
+          type: array
+        rows:
+          type: array
+        truncated:
+          type: boolean
+    errors: [REFUSED]
+  define:
+    type: effect
+    input:
+      type: object
+      properties:
+        name: &name
+          description: The view's name, which is what a query reads it by
+          type: string
+          pattern: ^[a-z][a-z0-9_]{0,62}$
+        sql:
+          description: The statement the view is, one a query could run
+          type: string
+          minLength: 1
+          maxLength: 65536
+        refresh:
+          description: Seconds between computations of a materialized view; absent, a plain view
+          type: integer
+          minimum: 3600
+      required: [name, sql]
+    errors: [REFUSED, RESERVED, EXHAUSTED]
+  drop:
+    type: effect
+    input:
+      type: object
+      properties:
+        name: *name
+      required: [name]
+    errors: [NOT_FOUND]
+
+exposition:
+  isolated: true
+  /:
+    auth:role: system:chronicles:query
+    mcp:tool: true
+    GET:
+      help:method:
+        title: What the log holds
+        description: >
+          The dialect queries are written in; the labels of `events`, with how many rows each
+          has, the first and last time of them and the fields their payloads have; the
+          components with a state in `states`, with how many entities each has and the fields
+          of the state; and the views defined over the log.
+      io:output: true
+      endpoint: describe
+    POST:
+      help:method:
+        title: Query the log
+        description: >
+          One statement, in the dialect `chronicles.queries.GET` names, over `events`, a row
+          for everything that happened (id, label, component, time, received, entity, version,
+          trace, payload), `states`, each entity as it stands (component, entity, version, time,
+          received, payload), and the views. At most 30 seconds and 10000 rows; at the rows,
+          `truncated` is true.
+      io:output: true
+      endpoint: query
+  /views/:name:
+    auth:role: system:chronicles:views
+    mcp:tool: true
+    PUT:
+      help:method:
+        title: Define a view
+        description: >
+          A view over the log, by a statement a query could run. Without `refresh` it is computed
+          when it is read; with `refresh`, in seconds and at least 3600, it is computed on that
+          cycle and read as a table. Defining a name again replaces the view.
+      help:route:
+        name: The view's name
+      endpoint: define
+    DELETE:
+      help:method: Drop a view
+      help:route:
+        name: The view's name
+      endpoint: drop

package/components/chronicles.queries/operations/define.js

@@ -0,0 +1,3 @@
+export async function effect(input, context) {
+  return await context.chronicles.define(input.name, input.sql, input.refresh)
+}

package/components/chronicles.queries/operations/describe.js

@@ -0,0 +1,3 @@
+export async function computation(_, context) {
+  return await context.chronicles.describe()
+}

package/components/chronicles.queries/operations/drop.js

@@ -0,0 +1,3 @@
+export async function effect(input, context) {
+  return await context.chronicles.drop(input.name)
+}

package/components/chronicles.queries/operations/query.js

@@ -0,0 +1,3 @@
+export async function computation(input, context) {
+  return await context.chronicles.query(input.sql)
+}

package/components/chronicles.queries/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from './toa.d.ts'
+
+// What a manifest does not state belongs here, and every run keeps it.

package/components/chronicles.queries/types/toa.d.ts

@@ -0,0 +1,44 @@
+// Written by `toa types`. Every run rewrites it.
+// What a manifest does not state belongs in a file of your own.
+
+import type { CodedError } from '@toa.io/core/types'
+
+export type DescribeOutput = {
+  /** What a query is written in */
+  dialect?: string
+  labels?: unknown[]
+  states?: unknown[]
+  views?: unknown[]
+}
+
+export type QueryInput = {
+  /** One statement over the log, in the dialect `describe` names */
+  sql: string
+}
+
+export type QueryOutput = {
+  columns?: unknown[]
+  rows?: unknown[]
+  truncated?: boolean
+}
+
+export type DefineInput = {
+  /** The view's name, which is what a query reads it by */
+  name: string
+  /** The statement the view is, one a query could run */
+  sql: string
+  /** Seconds between computations of a materialized view; absent, a plain view */
+  refresh?: number
+}
+
+export type DropInput = {
+  /** The view's name, which is what a query reads it by */
+  name: string
+}
+
+export interface Component {
+  describe: (request: { input?: null, task?: boolean }) => Promise<DescribeOutput>
+  query: (request: { input: QueryInput, task?: boolean }) => Promise<QueryOutput | CodedError<"REFUSED">>
+  define: (request: { input: DefineInput, task?: boolean }) => Promise<{} | null | undefined | CodedError<"REFUSED" | "RESERVED" | "EXHAUSTED">>
+  drop: (request: { input: DropInput, task?: boolean }) => Promise<{} | null | undefined | CodedError<"NOT_FOUND">>
+}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@toa.io/extensions.chronicles",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0-alpha.332",
+  "type": "module",
+  "description": "Toa Chronicles: a log of a context, kept in ClickHouse",
+  "author": "temich <tema.gurtovoy@gmail.com>",
+  "homepage": "https://github.com/toa-io/toa#readme",
+  "main": "transpiled/index.js",
+  "types": "transpiled/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/toa-io/toa.git"
+  },
+  "bugs": {
+    "url": "https://github.com/toa-io/toa/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "transpiled",
+    "components",
+    "readme.md",
+    "!**/tsconfig.tsbuildinfo",
+    "!**/*.test.*",
+    "!**/.env*"
+  ],
+  "scripts": {
+    "transpile": "tsc"
+  },
+  "dependencies": {
+    "@toa.io/core": "1.0.0-alpha.332",
+    "@toa.io/definitions": "1.0.0-alpha.332",
+    "@toa.io/generic": "1.0.0-alpha.332",
+    "openspan": "1.0.0-alpha.330"
+  }
+}