Summary#
An app where work is reviewed — a design, a report, a page an agent drafted — needs three things for what is reviewed: it must be kept with every version, people must comment on a particular version, and it must be shown safely, because a page somebody else wrote (an agent above all) must never run as your app inside the reviewer's session.
app Studio {
use Osysharp.Artifacts@0;
use Osysharp.Storage;
use Osysharp.Ui;
model "model/**/*.osy";
}Signature#
using Osysharp.Artifacts;
// The app answers who — nobody, until it does.
policy ReadsArtifactsOf(string subjectType, Guid subjectId) => …; // sees a subject's artifacts and comments
policy WritesArtifactsOf(string subjectType, Guid subjectId) => …; // publishes on it
policy CommentsOnArtifactsOf(string subjectType, Guid subjectId) => …; // comments (readers, until the app says)
Artifact PublishArtifact(string subjectType, Guid subjectId, string name, string contentType, byte[] bytes,
Guid? delegation = null); // new, or a new version under the same name
List<FileVersion> ArtifactVersions(Artifact artifact); // every version, the first first
ArtifactComment CommentOnArtifact(Artifact artifact, int version, string text, decimal? x = null, decimal? y = null);
void ResolveArtifactComment(ArtifactComment comment, bool resolved = true);
ArtifactView(FileVersion version, int h = 640) // one version, in the sandboxed frame
ArtifactFrame(version: Guid, title: string, <style props>) // the atom ArtifactView drawsDescription#
An artifact and its versions#
An Artifact is on one row of the app — its subject, named by its type and id ("Design", design.Id) — and holds
one FileAsset. Publishing under a name the subject already has calls File.Supersede on that file: the artifact is
the same row, the new content is the current version, and every earlier version stays, listed by ArtifactVersions
and viewable by ArtifactView (A file's history — supersede, and what each version keeps). A new version keeps the artifact's type; publish another
type under a name of its own.
var page = PublishArtifact("Design", design.Id, "index.html", "text/html", bytes, delegation: work.Id);
foreach (var v in ArtifactVersions(page)) {
Text("version " + v.Version);
ArtifactView(v, h: 480);
}What may be published#
text/html, image/png, image/jpeg, image/webp, image/gif, image/svg+xml, application/pdf, text/markdown,
text/plain and application/json. The bytes are checked against the type: a "picture" that is really a page is
refused, and so is text that is not UTF-8. A version is at most 25 MB. An HTML prototype must be one self-contained
page; output of several files is several artifacts.
The organisation's policy#
ArtifactsSetup holds two settings an organisation's policy governs for every app it runs: MaxBytes (a Range: it
may lower the 25 MB cap) and AllowPrototypes (a Lock: it may forbid HTML prototypes outright). PublishArtifact
reads them on every upload, so the organisation's word holds whatever the app sets.
Why the viewer is safe#
Artifact bytes are served only by the platform's route /_artifacts/{version}/{name}, and every answer carries the CSP
sandbox directive. The browser then gives the document an opaque origin, even when the address is opened directly
in a tab: its script cannot read your app's cookies or storage, connect-src 'none' stops it calling your app or
anywhere else, and it may not submit forms, open windows or navigate. Only HTML may run script at all; a picture, a
PDF or a note is sandboxed with none. ArtifactFrame sets sandbox="allow-scripts" on the frame as well, so the
sandbox is set twice, and it takes no address and no sandbox setting from your code.
A frame's request carries no sign-in, so the viewer's address is signed for the reader: the platform reads the
artifact as them (ReadsArtifactsOf) and only then mints a short-lived address naming that one version. Somebody who
may not see it gets an empty frame, and the address without its signature answers nothing.
⚠ Chromium will not show a PDF inside a sandboxed frame. Show a PDF artifact with the PDF viewer kit, or offer it as a
download, rather than in ArtifactView.
Comments#
A comment is on one version — it stays with the version it was written on when a new one is published — and may name
a point of the frame (x, y, each a fraction from 0 to 1). It is live: a page listing a version's comments shows a
new one as it is written. ResolveArtifactComment marks it done.
Examples#
A design's prototypes, each shown sandboxed#
app Studio {
use Osysharp.Artifacts@0;
use Osysharp.Storage;
use Osysharp.Ui;
model "model/**/*.osy";
}
using Osysharp.Ui;
using Osysharp.Artifacts;
entity Design {
[Required, MaxLength(80)] string Title;
security { allow read when IsAuthenticated; }
}
// Whoever may read a design sees its artifacts and publishes on it.
policy ReadsArtifactsOf(string subjectType, Guid subjectId) => subjectType == "Design" && Design.Any(d => d.Id == subjectId);
policy WritesArtifactsOf(string subjectType, Guid subjectId) => ReadsArtifactsOf(subjectType, subjectId);
[Route("/designs/{id}/artifacts")]
component DesignArtifacts(Guid id) {
render {
Stack(gap: 2) {
foreach (var a in Artifact.Where(x => x.SubjectType == "Design" && x.SubjectId == id).Include(x => x.File.CurrentVersion).ToList()) {
Text(a.Name);
ArtifactView(a.File.CurrentVersion, h: 720);
}
}
}
}Traps that cost real time#
The subject is two values, not a reference. An artifact can be on any row of any type, so it names it by type and id. Your policies decide what each pair means; a pair no policy admits is nobody's.
Frame(html) is not this. Frame shows a document with no script at all (Frame), which is what a mail
preview wants. A prototype needs its script, which is why it has a viewer of its own.
See also#
- A file's history — supersede, and what each version keeps — a file's history: what each version keeps, and
File.Supersede - Frame — a whole document in a frame with no script at all, for a mail preview