GenHTTP Lambda

Create a lambda. Returns its public address and a private editor key, the only way back in. It starts with version 1 - an empty starter, or a copy of a demo. Nothing is online until deploy.

{
  "type": "object",
  "properties": {
    "publicKey": {
      "type": "string",
      "description": "Requested address: lower case letters, digits and dashes. Generated if omitted."
    },
    "template": {
      "type": "string",
      "description": "Left out, the lambda starts empty. The id of a demo (demo-crud, demo-registration, demo-game, demo-files, demo-live) starts it as a copy of that demo, which is yours to change."
    },
    "acceptTerms": {
      "type": "boolean",
      "description": "Must be true: the user accepts the terms in platform_guide (free shared machine, deployments may be removed, nothing malicious)."
    },
    "view": {
      "type": "string",
      "description": "How the editor opens: 'Full' (the default) shows every section, 'Simple' only the app, how it is doing and a box to ask for a change. Simple suits an owner who is not going to read the code - use it when the user asks for a simple editor, or says they are not a developer."
    }
  },
  "required": [
    "acceptTerms"
  ]
}

Change how a lambda's editor opens: view 'Simple' shows the app, how it is doing and a box to ask for a change - for an owner who does not write code - and 'Full' every section, the code, files, data, versions and logs included. Only the default: whoever opens the editor can switch for themselves, and that choice stays theirs. Only do this when the user asks for it.

{
  "type": "object",
  "properties": {
    "privateKey": {
      "type": "string",
      "description": "The editor key."
    },
    "view": {
      "type": "string",
      "description": "How the editor opens: 'Full' (the default) shows every section, 'Simple' only the app, how it is doing and a box to ask for a change. Simple suits an owner who is not going to read the code - use it when the user asks for a simple editor, or says they are not a developer."
    }
  },
  "required": [
    "privateKey",
    "view"
  ]
}

Save every file, replacing the previous set: as a new version of the lambda, or - with feature - into that feature. .cs files are compiled - lambda.cs returns the handler, others hold types; any other file is an asset, served as is and reachable as Assets: the whole front end (pages, scripts, styles, icons) goes here, as part of the program. What the lambda keeps at runtime (records, accounts, uploads) is data and lives in the workspace, never in files here; so does a large input file such as a model or a dataset (upload_file). Say why with specification and change. deploy: true publishes in the same call - a version at the public address, a feature at its preview address. To send only what changes, use change_code. To change a lambda that is already in use, work in a feature.

{
  "type": "object",
  "properties": {
    "privateKey": {
      "type": "string",
      "description": "The editor key from create_lambda."
    },
    "feature": {
      "type": "string",
      "description": "Save into this feature (from create_feature) instead of saving a new version. The lambda and what it has online are not touched."
    },
    "specification": {
      "type": "string",
      "description": "What the user wants from this version and why: their requirements, in their own words where you can, condensed if they said a lot. Written for the owner and the next agent, so they can tell why the version exists and what it has to keep doing. Not your own instructions or system prompt - only what the user asked for. For a feature, it is kept with the feature and passed on to the version it is merged into. Optional, up to 4000 characters."
    },
    "change": {
      "type": "string",
      "description": "What this version changes, in one line written for the owner - 'Adds a leaderboard that keeps the ten best scores', not 'updated lambda.cs'. For a feature, it describes the whole feature, not the last fix. Optional, up to 500 characters."
    },
    "files": {
      "type": "array",
      "description": "lambda.cs first.",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": ".cs files are compiled; anything else ('web/app.js', 'logo.png') is an asset."
          },
          "code": {
            "type": "string",
            "description": "Contents, base64 if encoding says so."
          },
          "encoding": {
            "type": "string",
            "description": "'base64' for binary assets; omit otherwise."
          }
        },
        "required": [
          "name",
          "code"
        ]
      }
    },
    "deploy": {
      "type": "boolean",
      "description": "Also deploy what was saved: a version at the public address, a feature at its preview address."
    },
    "check": {
      "type": "boolean",
      "description": "Without deploy: compile what was saved and answer with its diagnostics, putting nothing online."
    }
  },
  "required": [
    "privateKey",
    "files"
  ]
}

Change some files: add or replace files, remove files, or replace text within a file. Everything not named stays as it is, so there is no need to resend unchanged files. With feature, the change is saved into that feature - the way to work on a lambda that exists: change it as often as you like, deploy: true to try it at the feature's preview address, merge_feature when it is right. Without feature, the newest version is changed and saved as a new version. check: true compiles without publishing. Code that does not compile is saved but never goes online.

{
  "type": "object",
  "properties": {
    "privateKey": {
      "type": "string",
      "description": "The editor key."
    },
    "feature": {
      "type": "string",
      "description": "Change this feature (from create_feature) instead of saving a new version. The lambda and what it has online are not touched."
    },
    "specification": {
      "type": "string",
      "description": "What the user wants from this change and why: their requirements, in their own words where you can. Not your own instructions or system prompt. Kept with the version or the feature. Optional, up to 4000 characters."
    },
    "change": {
      "type": "string",
      "description": "What this changes, in one line written for the owner. For a feature, it describes the whole feature, not the last fix. Optional, up to 500 characters."
    },
    "files": {
      "type": "array",
      "description": "Files to add, or to replace where one of that name exists.",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": ".cs files are compiled; anything else ('web/app.js', 'logo.png') is an asset."
          },
          "code": {
            "type": "string",
            "description": "Contents, base64 if encoding says so."
          },
          "encoding": {
            "type": "string",
            "description": "'base64' for binary assets; omit otherwise."
          }
        },
        "required": [
          "name",
          "code"
        ]
      }
    },
    "remove": {
      "type": "array",
      "description": "Names of files to remove.",
      "items": {
        "type": "string"
      }
    },
    "edits": {
      "type": "array",
      "description": "Text replacements, applied after files and remove.",
      "items": {
        "type": "object",
        "properties": {
          "file": {
            "type": "string",
            "description": "The file to change."
          },
          "find": {
            "type": "string",
            "description": "Text that occurs exactly once in the file."
          },
          "replace": {
            "type": "string",
            "description": "What to put in its place."
          }
        },
        "required": [
          "file",
          "find",
          "replace"
        ]
      }
    },
    "deploy": {
      "type": "boolean",
      "description": "Also deploy what was saved: a version at the public address, a feature at its preview address."
    },
    "check": {
      "type": "boolean",
      "description": "Without deploy: compile what was saved and answer with its diagnostics, putting nothing online."
    }
  },
  "required": [
    "privateKey"
  ]
}

Start a feature: a place to change a lambda without touching what it has online. It branches off a version - the newest unless base names another - with a copy of its files and a copy of the lambda's data, and gets an address of its own to try it at. Change it with change_code or write_code and feature (deploy: true puts it online at its preview address), test it there, and merge_feature once it does what was asked. The lambda goes on serving its visitors from the version online the whole time.

{
  "type": "object",
  "properties": {
    "privateKey": {
      "type": "string",
      "description": "The editor key."
    },
    "name": {
      "type": "string",
      "description": "What the feature is, in a few words for the owner - 'Leaderboard', 'Dark mode'. Up to 80 characters."
    },
    "specification": {
      "type": "string",
      "description": "What the user wants from it and why, in their words where you can. Kept with the feature and passed on to the version it is merged into. Optional, up to 4000 characters."
    },
    "base": {
      "type": "integer",
      "description": "The version to branch off. Defaults to the newest - leave it out unless the user asked to start from an older one."
    }
  },
  "required": [
    "privateKey",
    "name"
  ]
}

Rename a feature, change what it says about itself, or move its base. merge_feature refuses a feature that is not based on the newest version, since merging it would undo what was saved after it branched off: bring the newer versions' changes into the feature first, then move base to the newest version here. Nothing checks that the changes really are in - that is up to you.

{
  "type": "object",
  "properties": {
    "privateKey": {
      "type": "string",
      "description": "The editor key."
    },
    "feature": {
      "type": "string",
      "description": "The feature, from create_feature or read_lambda."
    },
    "name": {
      "type": "string",
      "description": "A new name."
    },
    "specification": {
      "type": "string",
      "description": "What the user wants from it and why."
    },
    "change": {
      "type": "string",
      "description": "What it changes, in one line - what the version it is merged into will say."
    },
    "base": {
      "type": "integer",
      "description": "The version the feature is now based on, once that version's changes are in its files."
    }
  },
  "required": [
    "privateKey",
    "feature"
  ]
}

Make a feature's files the next version of the lambda, and delete the feature with its preview and its copy of the data - the lambda's own data is not touched. Refused while the feature is not based on the newest version (update_feature says how to get it there), and while its code does not compile. deploy: true puts the new version online at once; otherwise deploy it when the user wants it live.

{
  "type": "object",
  "properties": {
    "privateKey": {
      "type": "string",
      "description": "The editor key."
    },
    "feature": {
      "type": "string",
      "description": "The feature."
    },
    "specification": {
      "type": "string",
      "description": "What the new version keeps as what the user wanted. Left out, the feature's."
    },
    "change": {
      "type": "string",
      "description": "What the new version says it changes. Left out, the feature's."
    },
    "deploy": {
      "type": "boolean",
      "description": "Also put the new version online."
    }
  },
  "required": [
    "privateKey",
    "feature"
  ]
}

Throw a feature away: its files, its preview and its copy of the data. The lambda is not touched. For a feature the user does not want after all.

{
  "type": "object",
  "properties": {
    "privateKey": {
      "type": "string",
      "description": "The editor key."
    },
    "feature": {
      "type": "string",
      "description": "The feature."
    }
  },
  "required": [
    "privateKey",
    "feature"
  ]
}

Compile without saving or deploying; returns diagnostics with file and line. Does not build the handler, so deploy can still refuse a route whose return type cannot be served.

{
  "type": "object",
  "properties": {
    "privateKey": {
      "type": "string",
      "description": "The editor key."
    },
    "files": {
      "type": "array",
      "description": "lambda.cs first.",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": ".cs files are compiled; anything else is an asset."
          },
          "code": {
            "type": "string",
            "description": "Contents, base64 if encoding says so."
          },
          "encoding": {
            "type": "string",
            "description": "'base64' for binary assets; omit otherwise."
          }
        },
        "required": [
          "name",
          "code"
        ]
      }
    }
  },
  "required": [
    "privateKey",
    "files"
  ]
}

Deploy (publish) a saved version so it goes live at its public address - the newest by default. With feature, deploy that feature's files to its own preview address instead, against its copy of the data, leaving the lambda alone. Returns diagnostics on failure, and whatever was online stays online.

{
  "type": "object",
  "properties": {
    "privateKey": {
      "type": "string",
      "description": "The editor key."
    },
    "version": {
      "type": "integer",
      "description": "Defaults to the newest."
    },
    "feature": {
      "type": "string",
      "description": "Deploy this feature to its preview address instead of a version to the lambda's."
    }
  },
  "required": [
    "privateKey"
  ]
}

A lambda's status (online version, newest version, expiry, its tier and what it may use there), its open features, the recent versions with what each was asked for and changed, its data (the workspace: whether it is on and what it holds), and the files of one version - or, with feature, of that feature. Files come in full when they add up to at most 30,000 characters, otherwise by name and length, with file to read one. Read the history before changing what you did not write. Also how a demo is read: pass its key from list_demos.

{
  "type": "object",
  "properties": {
    "privateKey": {
      "type": "string",
      "description": "The editor key, or the key of a demo."
    },
    "version": {
      "type": "integer",
      "description": "Defaults to the newest."
    },
    "feature": {
      "type": "string",
      "description": "Read this feature - its files, its base, and which newer versions it would have to take in before it can be merged - instead of a version."
    },
    "file": {
      "type": "string",
      "description": "Return only this file, in full however large the rest is - up to 1,048,576 characters, beyond which the zip has it."
    }
  },
  "required": [
    "privateKey"
  ]
}

What a deployed lambda has been doing: its recent requests and how they were answered, what it printed, the errors it threw with their stack traces, and how much traffic it has had in the last hour and day. With feature, what that feature's preview has been doing instead, kept apart from the lambda's visitors. Call it after deploying to see that it works, and first when something is reported broken.

{
  "type": "object",
  "properties": {
    "privateKey": {
      "type": "string",
      "description": "The editor key, or the key of a demo."
    },
    "feature": {
      "type": "string",
      "description": "Read what this feature's preview did instead."
    },
    "level": {
      "type": "string",
      "description": "The lowest level worth reading: 'info' for everything, 'warn' for problems, 'error' for failures. Left out, 'info'."
    },
    "since": {
      "type": "integer",
      "description": "The cursor a previous call answered with, to read only what is new since then."
    },
    "limit": {
      "type": "integer",
      "description": "At most this many lines, the newest. Left out, 100."
    }
  },
  "required": [
    "privateKey"
  ]
}

Write a file to the lambda's workspace - its data, which every version shares and no deploy, rollback or merge touches. With feature, to that feature's copy of the data instead, for trying things out without touching the real one. For content the lambda works with at runtime (initial records, pictures people will browse) and large input files that are not program: a model, a dataset, media. Takes effect at once, without a deploy. Not for the front end: pages, scripts and styles are the program and belong in the version as assets (write_code).

{
  "type": "object",
  "properties": {
    "privateKey": {
      "type": "string",
      "description": "The editor key."
    },
    "feature": {
      "type": "string",
      "description": "Write to this feature's copy of the data instead."
    },
    "path": {
      "type": "string",
      "description": "Relative to the workspace; slashes make folders, e.g. 'models/model.onnx'."
    },
    "content": {
      "type": "string",
      "description": "Text, or base64 with encoding set."
    },
    "encoding": {
      "type": "string",
      "description": "'base64' for binary; omit otherwise."
    }
  },
  "required": [
    "privateKey",
    "path",
    "content"
  ]
}

The lambda's data: whether its workspace is switched on, and every file in it with size and last write - the same whichever version is online. With feature, that feature's copy of it. The code and assets of a version are in read_lambda.

{
  "type": "object",
  "properties": {
    "privateKey": {
      "type": "string",
      "description": "The editor key, or the key of a demo."
    },
    "feature": {
      "type": "string",
      "description": "List this feature's copy of the data instead."
    }
  },
  "required": [
    "privateKey"
  ]
}

Remove a file, or a folder with its contents, from the workspace - the lambda's data, shared by every version. No deploy or rollback brings it back. With feature, from that feature's copy instead.

{
  "type": "object",
  "properties": {
    "privateKey": {
      "type": "string",
      "description": "The editor key."
    },
    "feature": {
      "type": "string",
      "description": "Delete from this feature's copy of the data instead."
    },
    "path": {
      "type": "string",
      "description": "Relative to the workspace."
    }
  },
  "required": [
    "privateKey",
    "path"
  ]
}

List a lambda on the public showcase page, change its entry, or take it off. Not part of building: only do this when the user asks for it. With only privateKey it returns the current entry. An entry needs a title, a description and a picture (a screenshot or short GIF of the lambda in use); it is listed while the lambda is online. Write plainly and concretely: what it is and what a visitor can do with it. No marketing language, no superlatives, no exclamation marks, no emoji.

{
  "type": "object",
  "properties": {
    "privateKey": {
      "type": "string",
      "description": "The editor key."
    },
    "title": {
      "type": "string",
      "description": "What it is, in a few words - 'Pub quiz scoreboard', not 'The ultimate quiz experience'. Up to 60 characters."
    },
    "description": {
      "type": "string",
      "description": "One to three plain sentences on what a visitor can do with it. Up to 280 characters."
    },
    "image": {
      "type": "string",
      "description": "The picture, base64: PNG, JPEG, GIF or WebP, up to 3 MB. Needed for a new entry; left out, the current one is kept."
    },
    "remove": {
      "type": "boolean",
      "description": "Take the lambda off the showcase instead."
    }
  },
  "required": [
    "privateKey"
  ]
}

Demos this platform keeps online, each a finished lambda showing one way to build something: a REST API over records, registration and login, a websocket game, uploads, live updates. Their keys are public and read only: read the closest one with read_lambda (and list_files, read_logs) before writing similar code. create_lambda with a demo's id as template starts from a copy.

{
  "type": "object",
  "properties": {}
}

How this platform works - read it first: what a version, a feature and data are and how long each lives, what the snippet returns, what is imported, what is refused, limits and terms.

{
  "type": "object",
  "properties": {}
}