Read CE from stdin, or file given by --from option

[rhuss]

Summary

Introduce the --from option for build and send commands, which a user can use to load CE from a file. The option defaults to -, which means the STDIN. Introduce the --from-format option as well, which defaults to json.

Description

The send and build commands may read the STDIN by default and expect there an event in JSON format.

This creates a nice and clean Unix-friendly flow:

$ kn event build --field a.b.c=foo | kn event send --to event-display

User might change that behavior with a new --from option:

$ kn event build --field a.b.c=foo -o json > event.json
# and later
$ kn event send --from event.json --to event-display

By adding the new --from option to the build sub-command as well, we could remove the event building options from send sub-command and keep nice and easy flow even for complex things (also with detecting tty on stdin/stdout we can automatically use json format instead of human-readable format):

$ kn event build --field a.b.c=foo
  | some-ce-modifing-command
  | kn event build --field a.d=bar
  | kn event send --to pod:event-sender

(The above example will build a basic CE with a.b.c=foo data, pass it to some command in JSON format, then add a.d=bar fields, and finally send it to K8s pod called event-sender)

Original description by @rhuss:

For users who don't know the CE spec very well, it feels strange to specify the payload of an event with --field event.data=something (also too long). Also we should allow to pick up the date from a file (which is not needed for other fields).

So from a UX pov I propose to introduce something like a --data and --data-from option.

[cardil]

The --field option is to easily build a data for event. It doesn't require any knowledge of CE spec. Using it like:

--field user.email=jdoe@example.org
--field user.name='John Doe'
--field score=154002

will produce a CE with data of:

{
  "user": {
    "email": "jdoe@example.org",
    "name": "John Doe",
  },
  "score": 154002
}

By the way. I also think the --data-from would be a good extension. I did plan to have it. That's also the one of the reason why kn event build command existed.

One could create an event template using kn event build and save it in project resources. And then use kn event send with --data-from (or rather maybe --load-from), and specify some overrides. That would make a nice UX by making command shorter.

Maybe I didn't get what you'd like to see here. Could you rephrase, so I can understand better?

[embano1]

Accepting stdin would be neat. Currently I pipe build output to curl which does support -d@- :)

[github-actions]

This issue is stale because it has been open for 90 days with no
activity. It will automatically close after 30 more days of
inactivity. Reopen the issue with /reopen. Mark the issue as
fresh by adding the comment /remove-lifecycle stale.

[rhuss]

/remove-lifecycle stale

[github-actions]

This issue is stale because it has been open for 90 days with no
activity. It will automatically close after 30 more days of
inactivity. Reopen the issue with /reopen. Mark the issue as
fresh by adding the comment /remove-lifecycle stale.

[rhuss]

/remove-lifecycle stale

[github-actions]

This issue is stale because it has been open for 90 days with no
activity. It will automatically close after 30 more days of
inactivity. Reopen the issue with /reopen. Mark the issue as
fresh by adding the comment /remove-lifecycle stale.

[cardil]

At @rhuss:

The issue description is misleading to me. I think you've been mistaken on how --field options works. Do my explanations clarify it for you?

Still, I think the option to provide data from STDIN is a good idea. But, that would rather be a different issue. Or just reword this one.

[rhuss]

Yeah, maybe I misunderstood the --field option. So, its only for building up the data: payload of a CE, right ? It's not for specifying fields on the CE itself ? ("field" in this sense sounds a bit counterintuitive).

Can you specify the full data directly with a --data, too ? No every CE has a JSON payload, and not sure if --field is capable of adding arrays.

[cardil]

Yes, the --field is only for building the payload in easy way. The idea was that you could build even complex payloads by specifying one value at a time.

For setting custom CE fields, I thought we could add --ce-property option.

The design docs mention --input as a way of loading previously saved CE. I see, that sometimes a better would be an option to load only payload from file. How about --payload option also? So, we would have --input to load the whole Ce as a base, and --payload to load just the payload of CE.

WDYT @rhuss?

[github-actions]

This issue is stale because it has been open for 90 days with no
activity. It will automatically close after 30 more days of
inactivity. Reopen the issue with /reopen. Mark the issue as
fresh by adding the comment /remove-lifecycle stale.

[cardil]

/remove-lifecycle stale

ping @rhuss

[rhuss]

So, why not just --data for being able to specify the full payload, as this reflects also the CE schema? And I like the suggestion from @embano1 to be able to take the payload only from standard input, too. Like with --data - or --data @-.

[cardil]

The vision doc has a templating section, which boils down to the --input param. The --input can take a file, stdin (-), or http(s) address, and that will expect the full payload (whole CE).

I think the input is a slightly better name than data, as data might imply a meaning it's about the CE data, instead of the whole CE.

[rhuss]

I would love to see an option to import the CE data only, not the full CE. This is especially useful for complex JSON payload. So I still would like a --data option for the payload only.

[github-actions]

This issue is stale because it has been open for 90 days with no
activity. It will automatically close after 30 more days of
inactivity. Reopen the issue with /reopen. Mark the issue as
fresh by adding the comment /remove-lifecycle stale.

[rhuss]

@cardil is --data something that you would still consider ?

[github-actions]

This issue is stale because it has been open for 90 days with no
activity. It will automatically close after 30 more days of
inactivity. Reopen the issue with /reopen. Mark the issue as
fresh by adding the comment /remove-lifecycle stale.

[rhuss]

/remove-lifecycle stale

[github-actions]

This issue is stale because it has been open for 90 days with no
activity. It will automatically close after 30 more days of
inactivity. Reopen the issue with /reopen. Mark the issue as
fresh by adding the comment /remove-lifecycle stale.

[rhuss]

/remove-lifecycle stale

[github-actions]

This issue is stale because it has been open for 90 days with no
activity. It will automatically close after 30 more days of
inactivity. Reopen the issue with /reopen. Mark the issue as
fresh by adding the comment /remove-lifecycle stale.

[rhuss]

/remove-lifecycle stale

[cardil]

Yes. I want to do that. In fact, the send command may read the stdin by default and expect there an event in JSON format.

This creates a nice and clean Unix-friendly flow:

$ kn event build --field a.b.c=foo | kn event send --to event-display

User might change that behavior with a new --from option:

$ kn event build --field a.b.c=foo -o json > event.json
# and later
$ kn event send --from event.json --to event-display

By adding the new --from option to the build sub-command as well, we could remove the event building options from send sub-command and keep nice and easy flow even for complex things (also with detecting tty on stdin/stdout we can automatically use json format instead of human-readable format):

$ kn event build --field a.b.c=foo
  | some-ce-modifing-command
  | kn event build --field a.d=bar
  | kn event send --to pod:event-sender

(The above example will build a basic CE with a.b.c=foo data, pass it to some command in JSON format, then add a.d=bar fields, and finally send it to K8s pod called event-sender)

I'll update the issue title and description accordingly. Thanks, @rhuss, for inspiration!

/triage accepted