monetization "stopped" state and monetizationstop / monetizationpending events

sublimator commented 5 years ago

@marcoscaceres For the moment using terms inline with the existing implementation :)

Having done some (non deployed) experiments internally re: pausing of streams and associated states/events, putting out this to get some feedback.

Adding a stopped state and redefining pending:

/**
 * Streaming has been initiated, yet first non zero packet is "pending"
 * It will normally transition from this `state` to `started`, yet not
 * always.
 */
export type PendingState = 'pending'

/**
 * Streaming has received a non zero packet and is still active
 */
export type StartedState = 'started'

/**
 * Streaming is inactive.
 * In the interest of keeping the amount of states necessary to handle down
 * this could mean a variety of things:
 *  - monetization may not be supported (no provider enabled)
 *  - may not have started yet
 *  - paused (potentially resumed)
 *  - finished completely (awaiting another request)
 *  - payment request denied by user intervention
 */
export type StoppedState = 'stopped'

document.monetization object

export type MonetizationState = PendingState | StartedState | StoppedState
export type MonetizationObject = EventTarget & {
  state: MonetizationState
}

Adding monetizationstop/monetizationpending events:

export interface MonetizationCommonEventDetail {
  // Web-Monetization-Id header present in the SPSP request
  requestId: string
  // The meta[@name="monetization"] @content value
  paymentPointer: string
}

export interface MonetizationStartEvent {
  type: 'monetizationstart'
  detail: MonetizationCommonEventDetail
}

export interface MonetizationProgressEvent {
  type: 'monetizationprogress'
  detail: {
    // The amount * received * at the destination specified in the SPSP endpoint
    amount: string
    assetCode: string
    assetScale: number
  } & MonetizationCommonEventDetail
}

export interface MonetizationPendingEvent {
  type: 'monetizationpending'
  detail: MonetizationCommonEventDetail
}

export interface MonetizationStopEvent {
  type: 'monetizationstop'
  detail: MonetizationCommonEventDetail
}

Excuse the TypeScript vs Web-IDL

marcoscaceres commented 5 years ago

Thanks @sublimator - the TypeScript is quite helpful!

I think we need to do also do a full comparison of what this could look like using a ReadableStream http://streams.spec.whatwg.org ... then we can also evaluate if we need to special-case anything (hopefully ReadableStream can capture everything we need).

Is that something might have time to look into?

sublimator commented 5 years ago

I am not really familiar with streams, what's the advantage there? Last I looked it was for binary data ? Having a quick squizz now

sublimator commented 5 years ago

The current impl events are essentially CustomEvent(...) with detail, not quite inline with the spec here. I had a quick look at the WEB streams API and it's not apparent to me (from that link at least) how you would use that for events. Would you JSON parse the chunks as they came in?

sublimator commented 5 years ago

Or are you talking about using the streams for the actual STREAM websocket connections?

marcoscaceres commented 5 years ago

I am not really familiar with streams, what's the advantage there?

All the work is done for us. Web platform primitive with well understood semantics.

Last I looked it was for binary data ?

No. They are for anything that "streams".

Having a quick squizz now

🤘

Would you JSON parse the chunks as they came in?

We can separate the JSON part out... it's more about "data" rather. Consider this in terms of a "session":

Money "starts" streaming ...
... more money steams as a particular rate... chunks are processed/acknowledged/transformed/displayed/etc.
Stream is eventually "closed" (e.g., money runs out, payment is complete, etc.).

Or are you talking about using the streams for the actual STREAM websocket connections?

Nope... don't know anything about STREAM - but maybe they work together?

sublimator commented 5 years ago

/**
 * Streaming is inactive.
 * In the interest of keeping the amount of states necessary to handle down
 * this could mean a variety of things:
 *  - monetization may not be supported (no provider enabled)
 *  - may not have started yet
 *  - paused (potentially resumed)
 *  - finished completely (awaiting another request)
 *  - payment request denied by user intervention
 */
export type StoppedState = 'stopped'

Something to ponder: streams can be actually paused. So it's kind of a stream of events huh ?

sublimator commented 5 years ago

https://developer.mozilla.org/en-US/docs/Web/API/Streams_API/Concepts

The data is read sequentially in small pieces called chunks. A chunk can be a single byte, or it can be something larger such as a typed array of a certain size. A single stream can contain chunks of different sizes and types.

Seems a bit of a stretch to me having not used them before. Maybe someone with some prior experience with the stream API has a bit more imagination for it.

what this could look like using a ReadableStream

Is there a Duplex type stream? You could model all the paid packets/events/etc as a read only stream, but there's also the ability to adjust bandwidth.

don't know anything about STREAM

I don't know much about what's under the hood either :) I think this is a question for @sharafian / @adrianhopebailie

sublimator commented 5 years ago

@marcoscaceres Streams are quite interesting. Definitely food for thought. Streams have a definite 'finality' to them that the above state representation doesn't. As you can see, for better or worse, the "stopped" state is quite ambiguous above. How did you imagine a user getting a handle on a stream ? Would it be a property of an event ? Would you have more than one ReadableStream for a given "session" (defined by requestId above) ? start / stop of a stream spanning a start / pause ? Should a new requestId be generated upon restarting/resuming a stream?

(edit: avoiding another email notification) I do wonder about multiple consumers of a given stream as well. Would each consumer get its own handle ?

I note that Streams aren't super well supported yet:
https://developer.mozilla.org/en-US/docs/Web/API/WritableStream#Browser_Compatibility https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream#Browser_Compatibility

marcoscaceres commented 5 years ago

Note I don't have a concrete proposal yet about how this should work... just feels like it's worth exploring. I'll hopefully get a bit of time to look into this in detail in the next few weeks, but maybe someone closer to the spec can do a deep dive? @tobie maybe?

sublimator commented 5 years ago

just feels like it's worth exploring

Noted :)

sublimator commented 4 years ago

@marcoscaceres Streams aside, what do you think about a stopped state and the new events as described above ?

sharafian commented 4 years ago

@adrianhopebailie we'd like to figure out how to implement this because currently the lack of a stopped state is impacting people who are using web monetization.

I wonder if we should be working on this repo only in the context of a longer term web standard and do our nearer term changes in the ILP RFCs?

adrianhopebailie commented 4 years ago

@sharafian what is blocking you at the moment?

If you want to do some experimenting with the implementation then I'd suggest just doing it and updating the spec to reflect the implementation when it settles.

sublimator commented 4 years ago

I guess he's thinking ahead to sharing the experimentations with other interested parties such as Cinnamon/Puma and getting them to try things out. Somewhere where the current experimentations can be documented.

adrianhopebailie commented 4 years ago

We should document everything here, not split the documentation. (I will mark the ILP version as deprecated and point here, should have done that already!)

We have a spec (see index.html in this repo) and we can keep iterating on it as fast as we can experiment.

But, obviously, we should consider people who are already using the APIs so we should try and stay backwards compatible.

sublimator commented 4 years ago

@adrianhopebailie

we should try and stay backwards compatible.

(edit: always forget the damn space after a > quote) I'm working on a PR today to try and get the spec closer to the current implementation (the events aren't even internally consistent in this repository) and then add the new events. Unfortunately, that's going to conflict with work @marcoscaceres has been doing :/

Backwards compatibility is at odds with a lot of what @marcoscaceres has been proposing (event name/shape changing/ consolidation, monetization object on the window). If we are going to be on one main repo:

I personally think we should merge @marcoscaceres PRs and then break ASAP with a bunch of changes at once (given the semantics of pending will change anyway) if there's solid reasoning that the changes proposed would be required for standardization.
- I'm fairly sure @sharafian (probably strongly) disagrees there however
- Most WM users are just <meta> sprinklers at this point I would imagine
- Even then, it'll hardly be a "let's upgrade the app from angularjs to angular 2.x series" type level of pain/work for people
Currently neither Ben or I have push/merge access to this repo

sublimator commented 4 years ago

@marcoscaceres Going to base the new events/states PR on your outstanding PRs, cause there's a bunch of good stuff in there: https://github.com/adrianhopebailie/web-monetization/pull/27

Reverting the event names from "start" to "monetizationstart" until we decide what to do

adrianhopebailie commented 4 years ago

I personally think we should merge @marcoscaceres PRs and then break ASAP with a bunch of changes at once (given the semantics of pending will change anyway) if there's solid reasoning that the changes proposed would be required for standardization.

What if we keep the old events but deprecate them in favour of new ones on a new object not attached to Document (per #23)?

sublimator commented 4 years ago

Thing is we have redefined "pending"... So breaks anyway ...

Still out, back online a bit later

sublimator commented 4 years ago

Keep old document events the same? Deprecated?

New semantics/events on new object?

U mean that?

tobie commented 4 years ago

Are the existing implementations gathering telemetry about API usage (in a privacy aware manner, of course)? Because that would definitely help make decisions about what can be deprecated.

sublimator commented 4 years ago

We don't have any client side API usage telemetry. We could add it I suppose?

It's just my personal guess, but I believe the vast majority of "users" just put the <meta> tag on their page and there is only a handful of more involved integrations. Deprecation/migration plan aside, I'm personally in favor of making all the "obvious" changes required for standardization while user count is still low.

Need @sharafian to weigh in as I'm sure he'd have a more accurate sense. He's on S.F. time.

tobie commented 4 years ago

Yes, it’s better to change the API early, but you also want to make sure you have a good idea of where you’re going with it so that doesn’t happen every other day.

Are you storing the use cases somewhere? Because that (along with the use cases that are clearly out of scope) would be super useful.

sublimator commented 4 years ago

clear use cases/scope

(edit: always forget the damn line after the >)

Noted!

@adrianhopebailie is pushing to keep information here and at https://webmonetization.org/ so I guess it would be good to list them somewhere at either of those.

There's the old spec, but I think most of it has been inlined here

adrianhopebailie commented 4 years ago

There's the old spec , but I think most of it has been inlined here

👍 New spec was a direct copy of the old so shouldn't have lost anything in the initial migration.

sublimator commented 4 years ago

Sorry, should have said 'most, if not all' :)

sharafian commented 4 years ago

There's nothing to stop us from emitting events under the current semantics on document.monetization and emitting events with the new names/semantics on window.monetization so we don't need to break a bunch of sites all at once. Even in the longer term we could make some kind of polyfill script available that ports the new API to the old one

sharafian commented 4 years ago

What I'd most like to do right now is release the new stopped state and the monetizationstop and monetizationpending events, because those won't be breaking to most sites.

Then we can save the rest of this conversation about shuffling fields around and whether or not to use streams and whether to add an imperative api and so on to be decided on without blocking people like cinnamon from their development

adrianhopebailie commented 4 years ago

Kamino closed and cloned this issue to interledger/webmonetization.org

adrianhopebailie / web-monetization

monetization "stopped" state and monetizationstop / monetizationpending events #24