Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@gits2501
gits2501 committed Jul 26, 2018
1 parent 8bb8582 commit bd5be18
Show file tree
Hide file tree
Showing 3 changed files with 103 additions and 115 deletions.
31 changes: 18 additions & 13 deletions EXAMPLES.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -121,7 +121,7 @@ So you can easily see something like `onStream` handler that:
2. saves `twitterOptions`/`accessToken` to apropriate places to be used in the next middleware
3. when it's done doing its thing, calls the next middleware

As you can see, twiz is not keen to stuff potentialy security sensitive data to `app` or `req` objects. It is given to your judgement to place your data where you see fit. `app` is used as storage in example just as an ilustration of a purpose, maybe you whould want some caching solution like `redis`/`memcache`.
As you can see, twiz is not keen to stuff potentialy security sensitive data to `app` or `req` objects. It is given to your judgement to place your data where you see fit. `app` is used as storage in example just as an ilustration of a purpose, maybe you would want some caching solution like `redis`/`memcache`.


## Chunked responses
Expand All @@ -148,11 +148,11 @@ A reference on how to [consume](https://stackoverflow.com/questions/6789703/how-

1. If your not sending `content-type`.

It is good idea to set `content-type` header on your server before you proxy first `chunk` back to client or else when stream finialy ends promise will reject with `noContentType` error. But your data will be already consumed in your in `onprogress(..)` callback.
It is good idea to set `content-type` header on your server before you proxy first `chunk` back to client or else when stream finialy ends promise will reject with `noContentType` error. But your data will already be consumed in your in `onprogress(..)` callback.

2. If you are sending `content-type`.

When your stream is consumed in `onprogress(..)` and it ends the promise will still resolve and you will have all your data that stream emmited in `o.data` also. Since your getting your data in `onprogress(..)` you might not want to receive it in your promise too. Same goes if your using callbacks and not promises. To stop all data from stream to resolve in promise set `chunked=true` in `args.options`.
When your stream is consumed in `onprogress(..)` and it ends, the promise will still resolve and you will have all your data that stream emmited in `o.data` also. Since you're getting your data in `onprogress(..)` you might not want to receive it in your promise too. Same goes if your using callbacks and not promises. To stop all data from stream to resolve in promise set `chunked=true` in `args.options`.

_**browser:**_
```js
Expand Down Expand Up @@ -191,20 +191,23 @@ _**browser:**_
background_noise: 'cicada low frequency',
intentions: 'lawfull good'
}
new_window:{
new_window: {
name: 'myPopUpWindow',
features: 'resizable=yes,height=613,width=400,left=400,top=300'
},

options:{ // twitter request options
options: { // twitter request options
method: 'POST',
path: 'statuses/update.json'
params: {
status: "Hooray, new tweet!"
}
}
}
}
}

twiz.OAuth(args)
.then(..)
})

```
_**browser(different page):**_
Expand All @@ -227,12 +230,12 @@ If there is no `session data` in url, function returns `undefined` and logs warn
## onEnd
### [⬑](#contents)

There is a second argument that is passed to your `tokenFound` handler. The `onEnd(..)` function.
It's use is to specify your function that will end the request as you see fit. For instance when you would like to use a template engine. `onEnd(..)` fires afther `access protected resources` (api) call but it does not end the response.
In `tokenFound` handler `twiz` has the `onEnd(..)` function available.
It's use is to specify your own function that will end the request as you see fit. For instance when you would like to use a template engine. `onEnd(..)` fires after `access protected resources` (api) call but it does not end the response.

_**node.js:**_
```js
app.on('tokenFound', function(found, onEnd){
app.on('tokenFound', function(found, twiz){

found
.then(function(accessToken){
Expand All @@ -242,9 +245,9 @@ _**node.js:**_

})

onEnd(function(apiData, res){ // happens after accessToken is found
twiz.onEnd(function(apiData, res){ // Happens after accessToken is found and api data received
res.render('signedInUI', { user: apiData.user.name }) // Uses server side template engine
// Ends response internally
// Ends response internally
})
})
```
Expand All @@ -262,7 +265,7 @@ Then the `twizlent.finishOAuth(..)` will get this `signedInUI` template in it's
## beforeSend
### [⬑](#contents)

On client side the `args.options` object can alse have a `beforeSend` property. It is a function that allows your to manipulate `xhr` instance before request is sent.
On client side the `args.options` object can also have a `beforeSend` property. It is a function that allows your to manipulate `xhr` instance before request is sent.

_**browser:**_
```js
Expand Down Expand Up @@ -298,7 +301,9 @@ The `args` object can have the `callback` property. You can specify there your c
1. **Promise is not avalable**
If there is `Promise`, `OAuth(..)` and `finishOAuth(..)` functions always return promise.
_**browser:**_
```js
args = {
...
Expand Down
64 changes: 35 additions & 29 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ It happens to be a 3-leg (step) dance, it's implementation could look like this:
As you can see there are 3 actors. Your web app/site, your server and twitter.
Twitter apis for authorization and authentication do not use `CORS`, that is, they do not emit `CORS` headers. So we cant send request to twitter directly from browser, but rather proxy them trough a Server, since request sent from server do not have any `CORS` restrictions applied. Your app is identified with `CONSUMER_KEY` and `CONSUMER_SECRET`. Both of which you get from twitter when you [create new app](https://apps.twitter.com/).

> On Twitter, user is internally associated with the a`ccess token`.
> On Twitter, user is internally associated with the `access token`.
Like user's `access token` , your app's `key` and `secret` are extreamly sensitive information. If anyone whould to get your app's key/secret then it can send requests to twitter just like they were sent from your app. It can try to mock you. Usually that's not what you want. Also, javascript is in plain text form in browser so we should never have our `CONSUMER_KEY/SECRET` there but on server. This is another good reason why we need a server to proxy our requests.
> Likewise if anyone is to get user's `access token`, then it may be able to send requests on user's behalf (who may actually never visited an app) and/or authorized such actions for that app. Altough, my guess is not in easy and straightforward way.
Expand Down Expand Up @@ -113,7 +113,11 @@ in browser:

bower: comming soon
local: <script src="src/twiz-client_bundle.js"></script>
local:

npm install twiz-client && npm run build

Then drop it in script tag: <script src="src/twiz-client_bundle.js"></script>
on server:
Expand Down Expand Up @@ -178,28 +182,7 @@ The only presumtions about a succesfull request is one with `200OK` status code,

`twizlent.OAuth(..)` will bring api data (`o.data`) if `twiz.haste(accessToken)` was called on the server and had `200OK` response. If not and the `twiz.continueOAuth()` is called it will receive `request token` and redirect user to twitter.

Then `o.redirection` is set to `true` in fullfuled handler. Also note that here everything (redirection to twitter, twitter's (re)direction back to app) happens in same window/tab in browser. Check [web site](https://github.com/gits2501/twiz/blob/master/README.md#web-site) workflow for popUps.

##### Test drive
[Test drive](https://gits2501.github.io/QuoteOwlet/) SPA (with `/oauth/authenticate`). Running on heroku free plan. May appear slow when dyno is waking up.

### Authorize or Authenticate

### [⬑](#contents)
By default `twizlent.OAuth(..)` will use the `/oauth/authorize` endpoint , but you can use the `/oauth/authenticate` like this:

_**browser:**_
```js
let args = {
...
endpoints:{
authorize: 'authenticate' // sets authenticate instead of authorize (notice no forward slash)
}
}
```


This is the so called [Sign in with Twitter](https://developer.twitter.com/en/docs/twitter-for-websites/log-in-with-twitter/guides/browser-sign-in-flow) flow, the one that uses `/oauth/authenticate` endpoint. That's how you would utilize it.
Then `o.redirection` is set to `true` in fullfuled handler. Also note that here everything (redirection to twitter, twitter's (re)direction back to app) happens in same window/tab in browser. Check [web site](#web-site) workflow for popUps.

Server is writen as express middleware.

Expand Down Expand Up @@ -257,11 +240,34 @@ _**node.js:**_
})
]
```

##### Test drive
[Test drive](https://gits2501.github.io/QuoteOwlet/) SPA (with `/oauth/authenticate`). Running on heroku free plan. May appear slow when dyno is waking up.

### Authorize or Authenticate

### [⬑](#contents)
By default `twizlent.OAuth(..)` will use the `/oauth/authorize` endpoint , but you can use the `/oauth/authenticate` like this:

_**browser:**_
```js
let args = {
...
endpoints:{
authorize: 'authenticate' // sets authenticate instead of authorize (notice no forward slash)
}
}
```


This is the so called [Sign in with Twitter](https://developer.twitter.com/en/docs/twitter-for-websites/log-in-with-twitter/guides/browser-sign-in-flow) flow, the one that uses `/oauth/authenticate` endpoint. That's how you would utilize it.


### Access Token

### [⬑](#contents)
Currently the minimum of what twiz see as valid `access token` is an object that has properties `oauth_token` and `oauth_token_secret` set. But it can have other parameters, like `screen_name`.
The `twiz-server` (here twizer) is by default an ending middleware, that is it will end the request. So call it before your error handling middlewares, if any. There are cases when twiz **does not end** the request, check [Stream](https://github.com/gits2501/twiz/blob/master/EXAMPLES.md#stream) usage. Errors will be sent to the next error handling midleware with `next(err)` calls and same errors will also be piped back to the browser.
The `twiz-server` (here twizer) is by default an ending middleware, that is it will end the request. So call it before your error handling middlewares, if any. There are cases when twiz **does not end** the request, check [Stream](/EXAMPLES.md#stream) usage. Errors will be sent to the next error handling midleware with `next(err)` calls and same errors will also be piped back to the browser.

### Prefligh

Expand Down Expand Up @@ -330,7 +336,7 @@ btn.addListener('onClick', function(){ // lets say we initiate

})
```
The `redirection_url` is now different then the page url then one from which we are making the request. Also we have `new_window` where we specify the window/popUp features where `redirection_url` will land . Making this more of a website use case.
The `redirection_url` is now different then the page url from which we are making the request. Also we have `new_window` where we specify the window/popUp features where `redirection_url` will land . Making this more of a website use case.
The `new_window` object contains two properties, `name` and `features`, they act the same as `windowName` and `windowFeatures` in [window.open()](https://developer.mozilla.org/en-US/docs/Web/API/Window/open). Note `o.window` reference to newly opened window / popUp instead of `o.redirection`.

_**browser(different page):**_
Expand All @@ -347,9 +353,9 @@ _**browser(different page):**_
// err is instance of Error()
// has err.name, err.message, err.stack ...
})
]

```
What this enables is to have completely custom popUp pages but same familiar popUp like for instance when you whould like to share something on twitter by pressing a twitter share button. Currently the downside is that users of the web site use case will get a popUp warning by browser which they have to allow before popUp apears.
What this enables is to have completely custom popUp pages but same familiar popUp, like for instance when you whould like to share something on twitter by pressing a twitter share button. Currently the downside is that users of the web site use case will get a popUp warning by browser which they have to allow before popUp apears.
Test drive [here]

_**node.js:**_
Expand Down Expand Up @@ -389,7 +395,7 @@ chunkedResponseWarning | Stream is consumed chunk by chunk in `xhr.onprogress(..
noRepeat | Cannot make another request with same `redirection(callback)` url.
spaWarning | Twitter authorization data not found in url.

`spaWarning` and `noRepeat` are errors that have informative character and usually you dont have to pay attention to them. They happen when user loads/relods page where `twizlent.finishOAuth(..)` is called on every load, imediately (which is valid). They are indications that `twizlent.finishOAuth(..)` will not run. For example, `spaWarning` means `twizlent.finishOAuth(..)` won't run on url that doesn't contain valid twitter authorization data. `noRepeat` means that you cannot make two requests with same twitter authorization data (like same `request token`). Check the [Stream](https://github.com/gits2501/twiz/blob/master/EXAMPLES.md#stream) for explanation of `chunkedResponseWarning`.
`spaWarning` and `noRepeat` are errors that have informative character and usually you dont have to pay attention to them. They happen when user loads/relods page where `twizlent.finishOAuth(..)` is called on every load, imediately (which is valid). They are indications that `twizlent.finishOAuth(..)` will not run. For example, `spaWarning` means `twizlent.finishOAuth(..)` won't run on url that doesn't contain valid twitter authorization data. `noRepeat` means that you cannot make two requests with same twitter authorization data (like same `request token`). Check the [Stream](/EXAMPLES.md#stream) for explanation of `chunkedResponseWarning`.

### Node.js

Expand Down

0 comments on commit bd5be18

Please sign in to comment.